1.3.1 • Published 3 years ago

dive-sdk v1.3.1

Weekly downloads
1
License
ISC
Repository
-
Last release
3 years ago

Dive Analytics Web Typescript SDK 1.3.1

Our SDK is written entirely in typescript with no native code requirements. The easiest way to get started is by cloning this repository and then link the folder with npm install.

Compatibility

DiveSDK it's a typescript lib. Works on any project that support typescript 3.8.3. However, use fetch, arrow functions and promises. Therefore: when you are going to compile it, if you want it to work in old browsers, make sure to use the appropriate polyfill for the browser version you want to make compatible.

Quick Start

  1. Clone the repository.

  2. Use the package manager npm to install the Dive Analytics Typescript SDK.

    npm install --save /path/to/dive-sdk

  3. Import the DiveSDK

    import {DiveSDK} from 'dive-sdk';

  4. Call DiveSDK.Init(DiveConfig) with the provided configuration.

Init the SDK

The method DiveSDK.Init(DiveConfig) initializes the SDK and sends the sdkStarted event.

  • Call this method as early as possible and only once
  • Create a new DiveConfig and fill the following parameters

DiveConfig

The Dive Team will provide all configuration elements:

  • AppToken - This is is the key that was generated for your game (UUID)
  • HashKey - Secret key used to hash the body of the events for consistency check with the server
  • ServerURL - This is the custom URL of your event server. This can also be updated remotely via Remote Settings
  • Environment - To properly test the events, use the DEV environment. If you are uploading the build to the stores use PROD environment.
  • Domain - It's the domain (without subdomain) of the page that you want to track. For example, if you want to track sub.mysite.com, add mysite.com as a value.
  • Logger: Logger configuration. An object that has one key: level, which determines the level of the log display in the console. Log levels are:
    • LogLevels.DISABLED: disable the message logging on browser console.
    • LogLevels.ERROR: only show errors on browser console.
    • LogLevels.WARNING: show warning and error messages on browser console.
    • LogLevels.INFO: show info, warning and error messages on browser console.
    • LogLevels.DEBUG: show debug, info, warning and error messages on browser console.

Init example

import {DiveSDK} from "dive-sdk";

DiveSDK
.Init({
    AppToken: "119bbf52-2248-416b-921d-16178847d121",
    HashKey: "EBmKgrWfrdfkerTt4mPs6Fxgs3Nv4kSQgjhgrUuRDcdUEr24wj",
    ServerURL: "https://public.dive.games/fallback-events",
    Environment: "DEV",
    Domain: "mysite.com",
    Logger: {
        level: LogLevels.ERROR
    }
});

Note: this is a initial configuration method. It is important to ensure that this method is called only once.

Custom Player Settings

Depending on your game, there are some configurations that MUST be set before launching the DiveSDK.Launch();

  • DiveSDK.getInstance().SetPlayerId(playerID:string); - This sets the ID you use to track the player.
  • DiveSDK.getInstance().SetServerSessionId(sessionID:string); - If your game has a custom server session id.
  • DiveSDK.getInstance().SetPlayerLevel(currentLevel:number); - This has to be setup on every startup and when the player levels up.
  • DiveSDK.getInstance().SetPlayerXp(currentXp:number); - This has to be setup on every startup and when the player gains xp.
  • DiveSDK.getInstance().SetGameVersion(gameVersion:string); - This sets a custom game version
  • DiveSDK.getInstance().SetDiveCid(cid:string); - This sets the Dive campaign id. This will override the one detected in deep link.

Note: DiveSDK class accepts method chaining. So, it’s possible to write all the configuration in a single line, as shown below:

import {DiveSDK} from "dive-sdk";

//1. Init the SDK using DiveConfig

//2. Set the Custom Player Settings
DiveSDK
.getInstance()
.SetPlayerId("1b314049-b9e8-4650-90ec-071f34d137ac")
.SetServerSessionId("98e6e003-b4c2-4ac6-9176-0350cafb8108")
.SetPlayerLevel(10)
.SetPlayerXp(9400)
.SetGameVersion("1.1")
.SetDiveCid("22");

//3. Trigger the launch with or without parameters

DiveSDK.getInstance().Launch();

Launch the SDK

The method DiveSDK.getInstance().Launch(); sends the appLaunched event.

  • Call it as soon as you have all the information required.
  • This method automatically adds device information parameters to the event body .
  • Only call this event once in the player session.
  • The Dive Team might request some custom parameters to be passed to the Launch event.

Example without custom parameters:

DiveSDK.getInstance().Launch();

Example with custom parameters:

DiveSDK.getInstance()
    .Launch(
        new EventBody()
            .AddParam("c_id", 1903839193)
            .AddParam("is_refreshed", false)
            .AddParam("extra_raw_params", "json string")
	);

Record Events

You can easily record custom events by using DiveSDK.getInstance().RecordEvent method and the EventBody class.

  1. Set the name of the event as string .
  2. Create a new EventBody() class.
  3. Call AddParam(string,object) to add custom event parameters to the event.

For example:

DiveSDK.getInstance()
	.RecordEvent("userLoggedIn", new EventBody() 
		.AddParam("login_type", "guest")
		.AddParam("coins", 2000)
		.AddParam("gems", 120)
    );

Important: The EventBody class support adding any object type. Avoid sending entire data class objects with nested elements, consider using a JSON string and check with the Dive Team for special cases.

Set the Logger with LogLevel.DEBUG in the DiveSDK to debug the current data being sent to the server. Your data will appear in the "body":{ } the other elements are automatically added by the sdk.

Raw JSON sent:

{
  "name": "userLoggedIn",
  "level_before": 3,
  "xp_before": 94000,
  "player_id": "34223465454",
  "s_session_id": "b98d5fbe-80b0-417d-837c-11a23ab4ad32",
  "game_ver": "1.0",
  "app_token": "cc326318-7783-404f-83e5-7220bb34b960",
  "platform": "web",
  "env": "DEV",
  "device_id": "c51348fb-8002-48ab-933e-9a20c1ef6e7f",
  "c_session_id": "b26b2fac-4920-45cf-b1de-edf74564cb37",
  "uuid": "2ad8c235-6541-41c2-b6cc-fbdb6a3896b6",
  "timezone": "-0300",
  "ts": "2020-07-27T16:54:06Z",
  "timestamp_utc": "2020-07-27T19:54:06Z",
  "unixts": 1595879646,
  "sdk_ver": "TS Dive SDK 1.3.0",
  "body": {
    "login_type": "guest",
    "coins": 2000,
    "gems": 120
  }
}

ScreenViewed event

To properly track the user screen flow, call the DiveSDK.getInstance().ScreenViewed method as soon as you display the Screen to the player. (example: lobby, menu, store, etc.)

  • Call the method every time you show the screen.
  • Set the screen name as string parameter.
  • The Dive Team will provide a list of relevant screens to track.
DiveSDK.getInstance().ScreenViewed("store");

The SDK will automatically remember the last screen viewed and send the correct screenViewed event

Error Event

To create a errorCreated event call the DiveSDK.getInstance().RecordError method. This is commonly used when you have unexpected situations in your game. (example: The store receipt validation failed, your user logged out or similar)

  • Every error reported must have a error code as string
  • To put the error in context add a description as string
DiveSDK.getInstance().RecordError("401", "Failed to validate Store Receipt. Invalid Token.");

Custom Event Headers

This is a special method used for rare tracking conditions. Use only if requested by the Dive Team.

  • DiveSDK.getInstance().SetCustomHeaderParam(headerName:string, headerValue:object);

Like the Custom Player Settings, this must be set before launch event and the header will persist for all events in this session.

//1. Set the Custom Header & other Custom Player Settings
DiveSDK.getInstance()
    .SetPlayerId("34223465454")
	.SetCustomHeaderParam("custom_tracking_campaing", "fb323451");

//2. Launch the sdk
DiveSDK.getInstance().Launch();

GDPR / CCPA

Forget Player

By using the method DiveSDK.getInstance().SetOptOut(true); you can notify Dive when a user has exercised their right to be forgotten.

This will instruct the Dive SDK to communicate the user's choice to be completely forgotten from any type of tracking on the client and/or server.

No requests from this device will be sent to the server in the future.

To resume tracking use DiveSDK.getInstance().SetOptOut(false);

This will start tracking again in the next DiveSDK.getInstance().Init

@types/node@types/ua-parser-jsua-parser-js
@infinitebrahmanuniverse/nolb-div@everything-registry/sub-chunk-1488@zalastax/nolb-div
1.3.1

3 years ago