@divegames/ts-sdk
v1.3.1
Published
Our SDK is written entirely in typescript with no native code requirements
Downloads
3
Keywords
Readme
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
Clone the repository.
Use the package manager npm to install the Dive Analytics Typescript SDK.
npm install @divegames/dive-ts-sdk
Import the DiveSDK
import {DiveSDK} from 'dive-sdk';
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 serverServerURL
- This is the custom URL of your event server. This can also be updated remotely via Remote SettingsEnvironment
- To properly test the events, use theDEV
environment. If you are uploading the build to the stores usePROD
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 versionDiveSDK.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.
- Set the name of the event as string .
- Create a new
EventBody
() class. - 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