@arkadiuminc/sdk 0.0.38 → 0.0.39

package/README.md

@@ -29,3 +29,12 @@ async function main() {
 main();
 ```
 
+
+## Reference documents
+
+- Analytics
+    - [App Insights](TODO)
+    - [Google Tag manager](TODO)
+    - [Standardized Spec for every game](https://arkadium.atlassian.net/wiki/spaces/DepartmentBusinessOperations/pages/23675756/Standardized+Spec+for+every+game+-+GA+AppInsights)
+    - [AppInsight stamper](https://arkadium.atlassian.net/wiki/spaces/PhoenixGames/pages/23993424/AppInsight+stamper)
+    - [Adaptive Sampling Implementation](https://arkadium.atlassian.net/wiki/spaces/PhoenixGames/pages/23897949/Adaptive+Sampling+Implementation)

package/dist/pkg/api/features/ads/index.test.d.ts

@@ -1,4 +0,0 @@
-/**
- * @jest-environment jsdom
- */
-export {};

package/dist/pkg/api/features/analytics/analytics.api.d.ts

@@ -1,30 +1,194 @@
 import { RpcProvider } from '../../core/rpc';
 import { GameIdReaderContract } from '../environment/environment.api';
+import { AnalyticProviderEnum, IAnalyticConfig } from './defs';
+import { DimensionsObject } from './dimensions';
 interface EnvironmentVersion {
-    GameKey: string;
-    GameVersion: string;
-    NestVersion: string;
-    SdkVersion: string;
+    gameKey: string;
+    gameVersion: string;
+    nestVersion: string;
+    sdkVersion: string;
 }
 export interface AnalyticsApiContract {
     setGameVersion(v: string): Promise<void>;
     setNestVersion(v: string): Promise<void>;
     getEnvVersion(): Promise<EnvironmentVersion>;
+    configureProvider(config: IAnalyticConfig): Promise<void>;
+    sendEvent(eventCategory: string, eventAction: string, dimensions: DimensionsObject): Promise<void>;
+    sendPageView(pageName: string, dimensions: DimensionsObject): Promise<void>;
+    trackException(exception: Error): Promise<void>;
 }
 export declare class AnalyticsApi implements AnalyticsApiContract {
     private gameReader;
     private rpcProvider;
+    private providers;
+    private activeProvidersTypes;
+    private info;
     constructor(gameReader: GameIdReaderContract, rpcProvider: RpcProvider);
     getEnvVersion(): Promise<EnvironmentVersion>;
-    private info;
     setGameVersion(v: string): Promise<void>;
     setNestVersion(v: string): Promise<void>;
+    configureProvider(config: IAnalyticConfig): Promise<void>;
+    sendEvent(eventCategory: string, eventAction: string, dimensions: DimensionsObject): Promise<void>;
+    sendPageView(pageName: string, dimensions: DimensionsObject): Promise<void>;
+    trackException(exception: Error): Promise<void>;
 }
 export declare class AnalyticsApiProxy implements AnalyticsApiContract {
     private rpcProvider;
+    CONSOLE: AnalyticProviderEnum;
+    APP_INSIGHTS: AnalyticProviderEnum;
+    GOOGLE: AnalyticProviderEnum;
+    private dimensionValues;
     constructor(rpcProvider: RpcProvider);
     setGameVersion(v: string): Promise<void>;
     setNestVersion(v: string): Promise<void>;
     getEnvVersion(): Promise<EnvironmentVersion>;
+    configureProvider(config: IAnalyticConfig): Promise<void>;
+    /**
+     * Low level method to report an analytics event
+     * Likely you can use the helper methods for common events instead.
+     * @param eventCategory {Event}
+     * @param eventAction {string} optional action. values depend on the event category
+     * @param dimensions record with dimensions to report
+     */
+    sendEvent(eventCategory: string, eventAction: string, dimensions: DimensionsObject): Promise<void>;
+    /**
+     * Low level method to report a page view
+     * Likely you can use the helper methods for common page views instead.
+     * @param pageName  the page name to report
+     * @param dimensions record with dimensions to report
+     */
+    sendPageView(pageName: string, dimensions: DimensionsObject): Promise<void>;
+    /**
+     * Use this method to report an exception back to analytics
+     * @param exception {Error} error to capture
+     */
+    trackException(exception: Error): Promise<void>;
+    setDimensions(dimensions: DimensionsObject): void;
+    /**
+     * Start of the Game (after preroll ends)
+     */
+    sendAppStartedEvent(dimensions?: DimensionsObject): void;
+    /**
+     * Loading ended, user can see Start button (after preroll ends)
+     */
+    sendMainScreenReadyEvent(dimensions?: DimensionsObject): void;
+    /**
+     * actions:
+     * User clicked on Start Button [action 'Loaded' if user continued previous game, otherwise New]
+     */
+    sendStartButtonClickedEvent(action: 'New' | 'Loaded', dimensions?: DimensionsObject): void;
+    /**
+     * User sees gameplay and are ready to make action
+     */
+    sendGameplayReadyEvent(dimensions?: DimensionsObject): void;
+    /**
+     * User made first move (any click on the page)
+     */
+    sendFirstMoveEvent(dimensions?: DimensionsObject): void;
+    /**
+     * User entered the first right answer (for word games or trivia games and other applicable games)
+     */
+    sendFirstRightAnswerEvent(dimensions?: DimensionsObject): void;
+    /**
+     * User made first match (for match-3, mahjongg and other applicable games)
+     */
+    sendFirsMatchEvent(dimensions?: DimensionsObject): void;
+    /**
+     * User made first shot (for shooters and other applicable games)
+     */
+    sendFirsShotEvent(dimensions?: DimensionsObject): void;
+    /**
+     * Users started new Round (Level). First round is Round 1 (not 0) (applicable for games with evergreen logic, not infinite games - before Nest changes to gameplay)
+     */
+    sendRoundEvent(dimensions?: DimensionsObject): void;
+    /**
+     * actions:
+     * - Finished - User successfully finished the Round (Level). First round is Round 1 (not 0) (applicable for games with evergreen logic, not infinite games - before Nest changes to gameplay)
+     * - Not_Finished - User didn't finish the Round (Level) successfully OR leaves the game OR skips the round OR Quit (applicable for games with evergreen logic, not infinite games - before Nest changes to gameplay)  {if possible several lose scenarios, add reason dimension}
+     *
+     * dimensions:
+     * - reason: No_Moves | Time_Out
+     */
+    sendRoundEndEvent(action: 'Finished' | 'Not_Finished', dimensions?: DimensionsObject): void;
+    /**
+     * actions:
+     *
+     * Win - User ended game because he wins ({Round} in Label only if game has it) (applicable for games with evergreen logic, not infinite games - before Nest changes to gameplay)
+     * Lose -User ended game because he loses or faces "No More Moves' situation ({Round} in Label only if game has it) (applicable for games with evergreen logic, not infinite games - before Nest changes to gameplay)
+     * Time_Out - User ended game because he runs of time ({Round} in Label only if game has it) (applicable for games with evergreen logic, not infinite games - before Nest changes to gameplay)
+     * New_Game - User ends game because he starts a new game: click on 'New Game', then click on 'Yes' ({Round} in Label only if game has it) (applicable for games with evergreen logic, not infinite games - before Nest changes to gameplay)
+     * Quit - User ends game because he quits a new game: click on 'Quit', then click on 'Yes' ({Round} in Label only if game has it) (applicable for games with evergreen logic, not infinite games - before Nest changes to gameplay)
+     * Restart - User starts the same game from the beginning again (mostly for Solitaire games): click on 'Restart', then click on 'Yes' ({Round} in Label only if game has it) (applicable for games with evergreen logic, not infinite games - before Nest changes to gameplay)
+     */
+    sendGameEndEvent(action: 'Win' | 'Lose' | 'Time_Out' | 'New_Game' | 'Quit' | 'Restart', dimensions?: DimensionsObject): void;
+    /**
+     * User clicked on Reshuffle (for mahjonggs and other applicable games)
+     */
+    sendReshuffleEvent(dimensions?: DimensionsObject): void;
+    /**
+     * User meet any type of errors
+     *
+     * expected dimensions:
+     * - reason
+     */
+    sendErrorEvent(dimensions?: DimensionsObject): void;
+    /**
+     * Users comes back from menu and sees the same game session [in games with limited gameplay time only]
+     */
+    sendGameScreenActionsEvent(dimensions?: DimensionsObject): void;
+    /**
+     * User turned sound on/off [for games where sound is a bar, and can be customized (e.g. 1/3 of max) - before Nest]
+     * User turned music on/off [for games where music is a bar, and can be customized to specific position (e.g. 1/3 of max)- before Nest]
+     */
+    sendMenuActionsEvent(action: 'Sound_On' | 'Sound_Off' | 'Music_On' | 'Music_Off', dimensions?: DimensionsObject): void;
+    /**
+     * User turned sound on/off [for games where only on/off option is available - after Nest]
+     */
+    sendSettingsEvent(dimensions?: DimensionsObject): void;
+    /**
+     * Clicks on Help button on Game_Screen or in the menu
+     */
+    sendHelpEvent(dimensions?: DimensionsObject): void;
+    /**
+     * User saw  the help pop up [if it appeared once per gameplay]
+     */
+    sendHelpShownEvent(dimensions?: DimensionsObject): void;
+    /**
+     * User clicks on different button  in help menu [if it appeared once per gameplay]
+     */
+    sendHelpPageEvent(action: 'Next' | 'Prev', dimensions?: DimensionsObject): void;
+    /**
+     * Impression of FUE - tutorial [aplicable for multiple stages tutorial which appear in different places]
+     */
+    sendFUEEvent(dimensions?: DimensionsObject): void;
+    /**
+     * User saw a sign in pop up (before Nest, sent by game. Should be missed if Nest implemented.)
+     * User logged in successfully  (before Nest, sent by game. Should be missed if Nest implemented.)
+     */
+    sendSignInPopUpEvent(action: 'Proposed' | 'Success', dimensions?: DimensionsObject): void;
+    /**
+     * User saw a sign in pop up (after Nest, sent by Nest. Should be missed if Nest not implemented.)
+     */
+    sendSignInClickedEvent(dimensions?: DimensionsObject): void;
+    /**
+     * User logged in successfully (returns with eagle id) (after Nest, sent by Nest. Should be missed if Nest not implemented.)
+     */
+    sendSignInSucceededEvent(dimensions?: DimensionsObject): void;
+    /**
+     * 1st page = page with start button
+     */
+    sendIntroScreenPageView(dimensions?: DimensionsObject): void;
+    /**
+     * Next page after user clicks on Start
+     */
+    sendGameScreenPageView(dimensions?: DimensionsObject): void;
+    /**
+     * Game over page == every game end, except Quit
+     */
+    sendGameOverPageView(dimensions?: DimensionsObject): void;
+    /**
+     * When player manually quits the game
+     */
+    sendQuitConfirmedPageView(dimensions?: DimensionsObject): void;
 }
 export {};

package/dist/pkg/api/features/analytics/analytics.api.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pkg/api/features/analytics/defs.d.ts

@@ -0,0 +1,10 @@
+export declare enum AnalyticProviderEnum {
+    CONSOLE = 1,
+    GOOGLE = 2,
+    APP_INSIGHTS = 3
+}
+export interface IAnalyticConfig {
+    appId: string;
+    provider: AnalyticProviderEnum;
+    providerConfig?: any;
+}

package/dist/pkg/api/features/analytics/dimensions.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Reference page:
+ * https://arkadium.atlassian.net/wiki/spaces/DepartmentBusinessOperations/pages/23675756/Standardized+Spec+for+every+game+-+GA+AppInsights
+ */
+export declare type DimensionsObject = Partial<Record<Dimension, string | number>>;
+export declare enum Dimension {
+    action = "action",
+    /**
+     * If game has infinite process, use Level dimensions
+     */
+    round = "round",
+    /**
+     *
+     */
+    score = "score",
+    /**
+     *
+     */
+    reason = "reason",
+    /**
+     * Domain, can be affected by iframe
+     */
+    domain = "domain",
+    /**
+     * getArenaName()
+     */
+    trafficSource = "trafficSource",
+    /**
+     * in seconds
+     * where 0 is Level Start|Round Start - should show at that moment from start each event happened
+     */
+    timespent = "timespent",
+    /**
+     *
+     */
+    gameVersion = "gameVersion",
+    /**
+     * If applicable, when test is running
+     */
+    abtestVersion = "abtestVersion",
+    /**
+     *
+     */
+    deviceType = "deviceType",
+    /**
+     *
+     */
+    frameRate = "frameRate",
+    /**
+     * If applicable
+     */
+    difficulty = "difficulty",
+    /**
+     * New - is first session
+     * Returning - otherwise
+     */
+    userType = "userType",
+    /**
+     * Should be sent with every event if possible. if user comes already logged in for ex. if user logs in in the game - start sending after login.
+     */
+    userID = "userID",
+    /**
+     * Should be sent with every event if possible. if user comes already logged in for ex. if user logs in in the game - start sending after login.
+     */
+    userSubscriptionId = "userSubscriptionId",
+    /**
+     * Should be sent with every event if possible. if user comes already logged in for ex. if user logs in in the game - start sending after login.
+     */
+    userSubscriptionPlan = "userSubscriptionPlan",
+    CD1 = "CD1",
+    CD2 = "CD2",
+    CD3 = "CD3",
+    CD4 = "CD4"
+}

package/dist/pkg/api/features/analytics/events.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Reference page:
+ * https://arkadium.atlassian.net/wiki/spaces/DepartmentBusinessOperations/pages/23675756/Standardized+Spec+for+every+game+-+GA+AppInsights
+ */
+export declare enum Event {
+    App_Started = "App_Started",
+    MainScreen_Ready = "MainScreen_Ready",
+    Start_Button_Clicked = "Start_Button_Clicked",
+    Gameplay_Ready = "Gameplay_Ready",
+    First_Move = "First_Move",
+    First_Right_Answer = "First_Right_Answer",
+    First_Match = "First_Match",
+    First_Shot = "First_Shot",
+    Round = "Round",
+    Round_End = "Round_End",
+    Game_End = "Game_End",
+    Reshuffle = "Reshuffle",
+    Error = "Error",
+    Game_Screen_Actions = "Game_Screen_Actions",
+    Menu_Actions = "Menu_Actions",
+    Settings = "Settings",
+    Help = "Help",
+    Help_Shown = "Help_Shown",
+    Help_Page = "Help_Page",
+    FUE = "FUE",
+    SignInPopUp = "SignInPopUp",
+    Sign_In_Clicked = "Sign_In_Clicked",
+    Sign_In_Successed = "Sign_In_Successed",
+    Reward = "Reward",
+    Boost = "Boost",
+    subscriptionBonus = "subscriptionBonus",
+    Gem_Purchase = "Gem_Purchase"
+}

package/dist/pkg/api/features/analytics/providers/AnalyticsProvider.d.ts

@@ -0,0 +1,17 @@
+import { DimensionsObject } from "../dimensions";
+declare type EventArr = [string, string, DimensionsObject];
+declare type PageViewArr = [string, DimensionsObject];
+export declare abstract class AnalyticsProvider {
+    protected config: any;
+    protected isReady: boolean;
+    protected unsentEvents: EventArr[];
+    protected unsentPageViews: PageViewArr[];
+    protected unsentExceptions: Error[];
+    constructor(config: any);
+    protected setup(): Promise<void>;
+    protected handleUnsent(): void;
+    sendEvent(eventCategory: string, eventAction: string, dimensions: DimensionsObject): void;
+    sendPageView(pageName: string, dimensions: DimensionsObject): void;
+    trackException(exception: Error): void;
+}
+export {};

package/dist/pkg/api/features/analytics/providers/AppInsightsProvider.d.ts

@@ -0,0 +1,26 @@
+import { DimensionsObject } from "../dimensions";
+import { AnalyticsProvider } from "./AnalyticsProvider";
+/**
+ * based on game-core-monorepo/packages/engine/src/Analytics/Provider/AppInsightsAnalytic.ts
+ * https://github.com/microsoft/ApplicationInsights-JS
+ */
+export interface IAppInsightConfig {
+    configUrl?: string;
+    defaultSamplingPercentage?: number;
+    selectedDomainsSamplingPercentage?: number;
+}
+export interface ICloudAppInsightConfig {
+    description: string;
+    instrumentationKey: string;
+    defaultSamplingPercentage: number;
+    selectedDomains: string[];
+    selectedDomainsSamplingPercentage: number;
+}
+export declare class AppInsightsProvider extends AnalyticsProvider {
+    private _aiTracker;
+    protected setup(): Promise<void>;
+    sendEvent(eventCategory: string, eventAction: string, dimensions: DimensionsObject): void;
+    sendPageView(pageName: string, dimensions: DimensionsObject): void;
+    trackException(exception: Error): void;
+    private getDefaultConfig;
+}

package/dist/pkg/api/features/analytics/providers/AppInsightsProvider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pkg/api/features/analytics/providers/ConsoleProvider.d.ts

@@ -0,0 +1,11 @@
+import { DimensionsObject } from "../dimensions";
+import { AnalyticsProvider } from "./AnalyticsProvider";
+/**
+ * based on game-core-monorepo/packages/engine/src/Analytics/Provider/ConsoleAnalytic.ts
+ */
+export declare class ConsoleProvider extends AnalyticsProvider {
+    protected setup(): Promise<void>;
+    sendEvent(eventCategory: string, eventAction: string, dimensions: DimensionsObject): void;
+    sendPageView(pageName: string, dimensions: DimensionsObject): void;
+    trackException(exception: Error): void;
+}

package/dist/pkg/api/features/analytics/providers/ConsoleProvider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pkg/api/features/analytics/providers/GoogleTagManagerProvider.d.ts

@@ -0,0 +1,20 @@
+import { DimensionsObject, Dimension } from "../dimensions";
+import { AnalyticsProvider } from "./AnalyticsProvider";
+/**
+ * based on game-core-monorepo/packages/engine/src/Analytics/Provider/GoogleAnalytic.ts
+ */
+declare global {
+    interface Window {
+        dataLayer?: any[];
+    }
+}
+export declare class GoogleTagManagerProvider extends AnalyticsProvider {
+    protected setup(): Promise<void>;
+    sendEvent(eventCategory: string, eventAction: string, dimensions: DimensionsObject): void;
+    mapDimensions(_dimensions: DimensionsObject): Partial<Record<Dimension, string | number>>;
+    computeLabel(eventCategory: string, eventAction: string, dimensions: DimensionsObject): string;
+    sendPageView(pageName: string, dimensions: DimensionsObject): void;
+    trackException(exception: Error): void;
+    private getDataLayer;
+    private gtag;
+}

package/dist/pkg/api/features/analytics/providers/GoogleTagManagerProvider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pkg/arkadium-game-sdk.d.ts

@@ -23,6 +23,8 @@ export declare class ArkadiumGameSdk {
     debugMode(enabled: boolean): void;
 }
 export { ApiEnv };
+export { Dimension } from './api/features/analytics/dimensions';
+export { Event } from './api/features/analytics/events';
 export declare class GameApi {
     version: string;
     private static sdk;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkadiuminc/sdk",
-  "version": "0.0.38",
+  "version": "0.0.39",
   "description": "",
   "keywords": [],
   "main": "dist/pkg/arkadium-sdk.umd.js",
@@ -27,6 +27,7 @@
     "build:game": "vite build --config vite.game.config.js",
     "build:arena": "vite build --config vite.arena.config.js",
     "build:docs": "typedoc --out docs --theme default src/arkadium-game-sdk.ts",
+    "build-fast": "npm run build:game && npm run build:arena",
     "build": "npm run build:pkg && npm run build:game && npm run build:arena && npm run build:docs",
     "start": "rollup -c rollup.config.ts -w",
     "test": "jest --coverage",
@@ -54,7 +55,7 @@
     "transform": {
       ".(ts|tsx)": "ts-jest"
     },
-    "testEnvironment": "node",
+    "testEnvironment": "jsdom",
     "testRegex": "(/__tests__/.*|\\.(test|spec))\\.(ts|tsx|js)$",
     "moduleFileExtensions": [
       "ts",
@@ -128,6 +129,7 @@
   },
   "dependencies": {
     "jsonpack": "^1.1.5",
-    "nanoid": "^5.0.4"
+    "nanoid": "^5.0.4",
+    "@microsoft/applicationinsights-web": "^3.0.4"
   }
 }

package/dist/pkg/index.html

@@ -1,14 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-    <head>
-        <title></title>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1">
-        <link href="css/style.css" rel="stylesheet">
-
-        <script src=""
-    </head>
-    <body>
-
-    </body>
-</html>