@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

npm install @pocketrocketgmbhgmbh/kpi-tracker

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

npm install @vue/composition-api

Usage

Vue 3 / Nuxt 3

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:

npm install @vue/composition-api

Then in your main.js:

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

Vue.use(VueCompositionAPI);

After that, the usage is identical to Vue 3:

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

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)

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

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:

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

cd kpi-tracker
npm install
npm run build

Package publishen

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:

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:

cd kpi-tracker
npm link

Dann in deinem Projekt:

npm link @pocketrocketgmbhgmbh/kpi-tracker

License

MIT