npm package: @pocketrocketgmbh/kpi-tracker
Description: Composable KPI tracking library for Vue 2 and Vue 3 games
Author: LucaPR24 luca.fries@pocket-rocket.io
Latest version: 1.4.3

# @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

### Vue 3 / Nuxt 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);
};
```

### Vue 2

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

### `useKpiTracker(initialTimesLeftToPlay?: number)`

Returns an object with KPI tracking state and methods.

#### State (Reactive Refs)

- `confirmedConsent: Ref<boolean>` - Age check confirmation status
- `enteredCrmData: Ref<boolean>` - CRM data entry status
- `gamePlayTimeStart: Ref<number | null>` - Game start timestamp
- `gamePlayTimeSeconds: Ref<number>` - Total play time in seconds
- `voucherRedeemed: Ref<boolean>` - Voucher redemption status
- `timesPlayed: Ref<number>` - Number of times played
- `selectedPerson: Ref<number>` - 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

### `useSession(config: KpiTrackerConfig, kpiTracker: UseKpiTrackerReturn)`

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<string | null>` - Current session fingerprint
- `userData: Ref<UserData | null>` - Collected user data

## Configuration

### `KpiTrackerConfig`

```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

### Component Example (Vue 3)

```vue
<template>
  <div>
    <button @click="handleAgeConfirm">Confirm Age</button>
    <input v-model.number="personCount" @input="handlePersonChange" />
    <button @click="handlePlay">Play</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { useKpiTracker, useSession } from "@pocketrocketgmbhgmbh/kpi-tracker";

const config = {
  gameId: process.env.VUE_APP_GAME_ID!,
  apiUrl: process.env.VUE_APP_API_URL!,
};

const kpiTracker = useKpiTracker(2);
const session = useSession(config, kpiTracker);

const personCount = ref(1);

const handleAgeConfirm = () => {
  kpiTracker.setConfirmedConsent(true);
};

const handlePersonChange = () => {
  kpiTracker.setSelectedPerson(personCount.value);
  kpiTracker.setEnteredCrmData(true);
};

const handlePlay = () => {
  kpiTracker.setGamePlayTimeStart(Date.now());
  // ... game logic
};
</script>
```

## 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

### Voraussetzungen

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)

### Package bauen

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

### Package publishen

```bash
npm publish --access public
```

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

### Version aktualisieren

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
```

### Lokale Entwicklung

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