@pocketrocketgmbhgmbh/kpi-tracker

Composable KPI tracking library for Vue 2 and Vue 3 games. This package provides a reusable solution for tracking game KPIs across multiple games.

Features

- ✅ Vue 2 and Vue 3 compatible
- ✅ Composable API (Composition API)
- ✅ TypeScript support
- ✅ Session management
- ✅ Fingerprint tracking
- ✅ KPI data collection

Installation

``bash
npm install @pocketrocketgmbhgmbh/kpi-tracker
`

For Vue 2 projects, you also need to install the Composition API plugin:

`bash
npm install @vue/composition-api
`

Usage

$3

`typescript
import { useKpiTracker, useSession } from "@pocketrocketgmbhgmbh/kpi-tracker";
import type { KpiTrackerConfig } from "@pocketrocketgmbhgmbh/kpi-tracker";

const config: KpiTrackerConfig = {
gameId: "your-game-id",
apiUrl: "https://api.example.com",
apiUsername: "your-username", // optional
apiPassword: "your-password", // optional
sessionStorageKey: "CUSTOM_SESSION_KEY", // optional
};

// Initialize KPI tracker
const kpiTracker = useKpiTracker(2); // 2 = initial times left to play

// Initialize session tracker
const session = useSession(config, kpiTracker);

// In your component
const handleAgeCheck = () => {
kpiTracker.setConfirmedConsent(true);
};

const handlePeopleSelect = (count: number) => {
kpiTracker.setSelectedPerson(count);
kpiTracker.setEnteredCrmData(true);
};

const handlePlayStart = () => {
kpiTracker.setGamePlayTimeStart(Date.now());
};

const handleGameEnd = () => {
const endTime = Date.now();
const playTimeSeconds = Math.floor(
(endTime - kpiTracker.gamePlayTimeStart.value!) / 1000
);
kpiTracker.setGamePlayTimeSeconds(playTimeSeconds);

// Initialize session with campaign ID
const campaignId =
new URL(location.href).searchParams.get("campaignId") ?? "";
session.getFingerprintAndInitializeSession(campaignId);
};
`

$3

For Vue 2, you need to install @vue/composition-api first:

`bash
npm install @vue/composition-api
`

Then in your main.js:

`javascript
import Vue from "vue";
import VueCompositionAPI from "@vue/composition-api";

Vue.use(VueCompositionAPI);
`

After that, the usage is identical to Vue 3:

`typescript
import { useKpiTracker, useSession } from "@pocketrocketgmbhgmbh/kpi-tracker";

// Same as Vue 3 example above
`

API Reference

$3

Returns an object with KPI tracking state and methods.

#### State (Reactive Refs)

- confirmedConsent: Ref - Age check confirmation status
- enteredCrmData: Ref - CRM data entry status
- gamePlayTimeStart: Ref - Game start timestamp
- gamePlayTimeSeconds: Ref - Total play time in seconds
- voucherRedeemed: Ref - Voucher redemption status
- timesPlayed: Ref - Number of times played
- selectedPerson: Ref - Number of selected persons

#### Methods

- setConfirmedConsent(value: boolean) - Set age check confirmation
- setEnteredCrmData(value: boolean) - Set CRM data entry status
- setGamePlayTimeStart(timestamp: number | null) - Set game start time
- setGamePlayTimeSeconds(seconds: number) - Set play time in seconds
- setVoucherRedeemed(value: boolean) - Set voucher redemption status
- incrementTimesPlayed() - Increment play counter
- setSelectedPerson(person: number) - Set number of persons
- resetTrackingData() - Reset all tracking data
- resetGame(timesLeftToPlay?: number) - Reset game state
- getKpiData() - Get current KPI data object

$3

Returns an object with session management methods.

#### Methods

- getFingerprintAndInitializeSession(campaignId: string) - Initialize session with fingerprint
- findSession(campaignId: string) - Find or create session
- createUpdateSession(identifier: string, campaignId: string) - Create or update session
- resetSessionId() - Reset session ID

#### State

- fingerprint: Ref - Current session fingerprint
- userData: Ref - Collected user data

Configuration

$3

`typescript
interface KpiTrackerConfig {
gameId: string; // Required: Your game ID
apiUrl: string; // Required: API base URL
apiUsername?: string; // Optional: Basic auth username
apiPassword?: string; // Optional: Basic auth password
sessionStorageKey?: string; // Optional: Custom localStorage key
}
`

Example Integration

$3

`vue



`

Building the Package

To build the package for distribution:

`bash
cd kpi-tracker
npm install
npm run build
`

This will create the dist/ folder with compiled files.

Publishing

$3

1. Stelle sicher, dass du bei npm eingeloggt bist:

`bash
npm login
`

2. Stelle sicher, dass der Scope @pocketrocketgmbhgmbh existiert oder erstelle eine Organisation auf npm:
- Gehe zu https://www.npmjs.com/
- Erstelle eine Organisation namens "pocketrocketgmbh" (falls noch nicht vorhanden)

$3

`bash
cd kpi-tracker
npm install
npm run build
`

$3

`bash
npm publish --access public
`

Der --access public Flag ist wichtig, da scoped packages standardmäßig privat sind.

$3

Wenn du Änderungen gemacht hast und eine neue Version publishen möchtest:

`bash
npm version patch # für Bugfixes (1.0.0 -> 1.0.1)
npm version minor # für neue Features (1.0.0 -> 1.1.0)
npm version major # für Breaking Changes (1.0.0 -> 2.0.0)
npm publish --access public
`

$3

Für lokale Entwicklung kannst du das Package auch lokal verlinken:

`bash
cd kpi-tracker
npm link
`

Dann in deinem Projekt:

`bash
npm link @pocketrocketgmbhgmbh/kpi-tracker
``

License

MIT