API Reference

Unity

Install Telescope SDK

To integrate Telescope Labs analytics SDK, you can use one of the two methods: by using the Unity Package Manager (recommended) or by manually importing the unitypackage.

Unity Package Manager

  1. Open the Package Manager (Window → Package Manager), click + in the top left corner and select Add package from git URL.

  2. Copy the repository URL https://github.com/TelescopeLabs/Telescope-SDK-Unity.git to the input box and click Add.

  3. Wait for the Unity Package Manager to download the package.

Import Unity Package

  1. Download Telescoplabs.unitypackage from link.
  2. In the Unity Editor menu, open Assets → Import Package → Custom Package.
  3. Select the Telescopelabs.unitypackage that you have downloaded.

Initializing SDK

You don't need to manually initialize the sdk. The SDK generates a game object called Telescope once game started.

SDK Settings

  1. You will need your game api key for initializing your library. You can get your api key from link.
  2. To initialize the library, first open the unity project settings menu for Telescope. (Edit → Project Settings → Telescope) Then, enter your game api key into the Api Key input fields within the inspector.

After these steps are done, you are ready to view your game data.

🚧

Warning

The SDK won't send game data if you don't enter an api key. However, It will store events and send data when enabled.

SDK Features

Show Debug

It is a feature in project settings menu for Telescope. It will print all logs coming from the SDK to console with prefix [Telescope] if enabled.

Enabled

It is a feature in project settings menu for Telescope. The SDK won't send or buffer track data if disabled.

Flush Interval

The SDK uses the flush interval to determine when to send buffered events to server. Its default value is 60 seconds. You may need to set a appropriate flush interval value that fits your game or application's use case.

🚧

Warning

You can't set less than 15 seconds or bigger than 300 seconds due to optimization.

Session Timeout

The SDK uses the timeout to determine when to end a session. If there has been a period of inactivity, such as the game running in the background or paused for too long, the SDK will end the session. Its default value is 10 minutes and minimum value is 60 seconds. You may need to set a appropriate timeout value that fits your game or application's use case, to avoid ending sessions prematurely.

Custom User ID

  • The SDK will automatically generate a user id.
  • It is useful to set a custom user id when you match the users with collected data from different sources.

If you want to use custom user id, you should call the SetCustomUserID method and pass your desired user id as parameter. This will ensure that all events including the auto-triggered events will use the custom user id that you have set. Here's the code to set a custom user id:

Telescope.SetCustomUserID("my_custom_user_id");

This will set "my_custom_user_id" as the user id for all events including the auto-triggered events.

📖

Note

You have to ensure that the SetCustomUserId is called in awake method. The SDK will be initialized and will generate a user id with some events between awake and start methods.

Buffering

The SDK has a buffer structure that allows it to collect and store events locally before sending them to the server. The SDK periodically sends the buffered events to the server. If for any reason the SDK is unable to send the events to the server, it will retain the buffered events and try to send them again later.

This buffer structure serves several important purposes:

  • Reliability: By buffering events locally before sending them to the server, the SDK ensures that events are not lost if the server is unavailable or if there is a temporary network issue. This improves the reliability of event tracking and ensures that all events are eventually sent to the server.
  • Performance: Sending events to the server one at a time can be resource-intensive, especially if the application generates a large number of events. By buffering events locally, the SDK can send them to the server in batches, which improves the performance and reduces the load on both the client and the server.
  • Network efficiency: If a device is in an area with weak or unstable network connection, sending events one by one would be problematic, as it would take too long for the events to reach the server. By buffering events, the SDK can wait for a stable connection and send events in a batch, reducing the chances of data loss and increasing network efficiency.
  • Data Integrity: By buffering events, the SDK can ensure that the data is not lost if the application crashes or if there is a problem with the device before the data is sent. This ensures the integrity of the data being sent to the server.

Overall, the buffer structure is an important feature of the SDK that improves the reliability, performance, network efficiency, and data integrity of event tracking.

Session Handling

The SDK includes a session handling feature that allows it to track and manage the lifecycle of a user's session within the game. The feature includes several key components:

  • Session Start Event: When the game is first started, the SDK immediately sends a "Session Start" event to the server. This event includes information about the start of the session, such as the user ID, session ID, and timestamp.
  • Game Running Event: The SDK sends a "Game Running" event periodically, such as a heartbeat. This event is used to detect if a session has reached a timeout and therefore needs to end. It also helps to detect if the game has crashed, and end the session accordingly.
  • Timeout Detection: The SDK checks session periodically to detect if a session has reached a timeout. If there has been a period of inactivity, such as the game running in the background or paused for too long, the SDK will end the session.
  • End Session Event: When the session ends, the SDK sends an "End Session" event to the server. This event includes information about the end of the session, such as the user ID, session ID, and timestamp.

This session handling feature is useful for tracking user engagement and understanding how users interact with the game. By sending session start and end events, the SDK allows you to track session duration and analyze user behavior within the game. The "Game Running" event serves as a heartbeat, allowing you to detect if a session has reached a timeout or if the game has crashed, and end the session accordingly.

Events related to session are all internal, auto-triggered events, which are automatically sent by the SDK to the server at the appropriate times.

📖

Note

It's important to note that the SDK uses the timeout to determine when to end a session. It's important to set a appropriate timeout value that fits your game or application's use case, to avoid ending sessions prematurely.

Network Status

When the SDK detects that there is no network connection, it will continue to store events locally in a buffer. Once a connection is re-established, the SDK will send the buffered events to the server. This feature improves the reliability of event tracking, as it ensures that all events are eventually sent to the server, even if the player is in an area with poor or unstable network connectivity.

Event Tracking

The SDK provides a Telescope class with several static methods that developers can use to track events and send values.

📘

Info

Note that the SDK adds tracks to the buffer and sends them as a batch with intervals you set Flush Interval in Telescope Settings.

Events

Users

Function prototype:

Telescope.Users(int? advertisingid = null, int? age = null, int? androidid = null, string appversionid = null, bool? cheater = false, string country = null, string customuid = null, string deviceid = null, string firstappversionid = null, string idfa = null, string idfv = null, DateTime? lasttime = null, int? level = null, string locale = null, DateTime? min_createtime = null, string osversionid = null, int? paying_status = null, int? paymentcount = null, int? paymentsum = null, int? publisherid = null, int? push_available = null, int? sbspaymentcount = null, int? sbspaymentsum = null, int? subcampaignid = null, bool? tester = false, int? timezoneoffset = null, string useremail = null, string username = null, string userphone = null, string userphoto = null, string walletid_1 = null, string walletid_2 = null, string walletid_3 = null);

Optional Parameters:

  • advertisingid:
  • age:
  • androidid:
  • appversionid:
  • cheater:
  • country:
  • customuid:
  • deviceid:
  • firstappversionid:
  • idfa:
  • idfv:
  • lasttime:
  • level:
  • locale:
  • min_createtime:
  • osversionid:
  • paying_status:
  • paymentcount:
  • paymentsum:
  • publisherid:
  • push_available:
  • sbspaymentcount:
  • sbspaymentsum:
  • subcampaignid:
  • tester:
  • timezoneoffset:
  • useremail:
  • username:
  • userphone:
  • userphoto:
  • walletid_1:
  • walletid_2:
  • walletid_3:

Example usage:

Telescope.AdImpressions(username: "lion", walletid_1: "xxxxxxxx");

AdImpressions

Function prototype:

Telescope.AdImpressions(string abtestvalues = null, string ad_network = null, string ad_placement = null, string ad_source = null, string ad_unit = null, string appversion = null, string appversionid = null, bool? cheater = false, string country = null, DateTime? created = null, string device = null, string deviceid = null, int? eventlevel = null, string firstappversion = null, string firstappversionid = null, DateTime? firstpaymentdate = null, DateTime? lastpaymentdate = null, int? level = null, string locale = null, string location = null, int? locationid = null, string osversion = null, string osversionid = null, int? paymentcount = null, double? paymentsum = null, double? revenue = null, DateTime? sbsfirstpaymentdate = null, int? sbspaymentcount = null, double? sbspaymentsum = null, string sdkversion = null, int? sdkversionid = null, string segmentvalues = null, bool? tester = false);

Optional Parameters:

  • abtestvalues:
  • ad_network:
  • ad_placement:
  • ad_source:
  • ad_unit:
  • appversion:
  • appversionid:
  • cheater:
  • country:
  • created:
  • device:
  • deviceid:
  • eventlevel:
  • firstappversion:
  • firstappversionid:
  • firstpaymentdate:
  • lastpaymentdate:
  • level:
  • locale:
  • location:
  • locationid:
  • osversion:
  • osversionid:
  • paymentcount:
  • paymentsum:
  • revenue:
  • sbsfirstpaymentdate:
  • sbspaymentcount:
  • sbspaymentsum:
  • sdkversion:
  • sdkversionid:
  • segmentvalues:
  • tester:

Example usage:

Telescope.AdImpressions(level: 3, ad_source: "google", ad_unit: "s", ad_placement: "table");

IngamePurchases

Function prototype:

Telescope.IngamePurchases(int? amount = null, string appversionid = null, bool? cheater = false, string country = null, string currency = null, string deviceid = null, string firstappversionid = null, string item = null, string itemtype = null, int? level = null, string locale = null, string osversionid = null, int? p1 = null, int? paying_status = null, int? paymentcount = null, int? paymentsum = null, double? price = null, int? sbspaymentcount = null, int? sbspaymentsum = null, bool? tester = false);

Optional Parameters:

  • amount:
  • appversionid:
  • cheater:
  • country:
  • currency:
  • deviceid:
  • firstappversionid:
  • item:
  • itemtype:
  • level:
  • locale:
  • osversionid:
  • p1:
  • paying_status:
  • paymentcount:
  • paymentsum:
  • price:
  • sbspaymentcount:
  • sbspaymentsum:
  • tester:

Example usage:

Telescope.IngamePurchases(item: "sword", currency: "gold", amount: 1, paying_status: 1, price: 97512);

LevelUps

Function prototype:

Telescope.Levelups(string appversionid = null, bool? cheater = false, string country = null, string deviceid = null, int? eventlevel = null, string firstappversionid = null, int? level = null, string locale = null, string osversionid = null, int? paying_status = null, int? paymentcount = null, int? paymentsum = null, int? sbspaymentcount = null, int? sbspaymentsum = null, bool? tester = false);

Optional Parameters:

  • appversionid:
  • cheater:
  • country:
  • deviceid:
  • eventlevel:
  • firstappversionid:
  • level:
  • locale:
  • osversionid:
  • paying_status:
  • paymentcount:
  • paymentsum:
  • sbspaymentcount:
  • sbspaymentsum:
  • tester:

Example usage:

Telescope.Levelups(eventlevel: 5, level: 6, tester: true, cheater: true);

LevelUpsCurrencies

Function prototype:

Telescope.LevelUpsCurrencies(string appversionid = null, bool? cheater = false, string country = null, string currencytype = null, string deviceid = null, string firstappversionid = null, int? level = null, string locale = null, string osversionid = null, int? p1 = null, int? paying_status = null, int? paymentcount = null, int? paymentsum = null, int? sbspaymentcount = null, int? sbspaymentsum = null, bool? tester = false);

Optional Parameters:

  • appversionid:
  • cheater:
  • country:
  • currencytype:
  • deviceid:
  • firstappversionid:
  • level:
  • locale:
  • osversionid:
  • p1:
  • paying_status:
  • paymentcount:
  • paymentsum:
  • sbspaymentcount:
  • sbspaymentsum:
  • tester:

Example usage:

Telescope.LevelUpsCurrencies(level: 1, appversionid: "19");

Payments

Function prototype:

Telescope.Payments(string paymentid, string appversionid = null, bool? cheater = false, string country = null, string currency = null, string deviceid = null, string firstappversionid = null, int? level = null, string locale = null, string osversionid = null, int? paymentcount = null, int? paymentsum = null, double? price = null, double? priceusd = null, int? product = null, int? sbspaymentcount = null, int? sbspaymentsum = null, bool? tester = false, int? valid = null);

Required Parameters:

  • paymentid:

Optional Parameters:

  • appversionid:
  • cheater:
  • country:
  • currency:
  • deviceid:
  • firstappversionid:
  • level:
  • locale:
  • osversionid:
  • paymentcount:
  • paymentsum:
  • price:
  • priceusd:
  • product:
  • sbspaymentcount:
  • sbspaymentsum:
  • tester:
  • valid:

Example usage:

Telescope.Payments("11223344", price: 99.9, product: 556677, paymentcount: 10, country: "germany");

Progressions

Function prototype:

Telescope.Progressions(string appversionid = null, bool? cheater = false, string country = null, int? currencytype = null, string deviceid = null, int? difficulty = null, int? duration = null, string firstappversionid = null, int? level = null, string locale = null, int? locationid = null, int? locationsource = null, string osversionid = null, int? paying_status = null, int? paymentcount = null, int? paymentsum = null, int? sbspaymentcount = null, int? sbspaymentsum = null, int? success = null, bool? tester = false);

Optional Parameters:

  • appversionid:
  • cheater:
  • country:
  • currencytype:
  • deviceid:
  • difficulty:
  • duration:
  • firstappversionid:
  • level:
  • locale:
  • locationid:
  • locationsource:
  • osversionid:
  • paying_status:
  • paymentcount:
  • paymentsum:
  • sbspaymentcount:
  • sbspaymentsum:
  • success:
  • tester:

Example usage:

Telescope.Progressions(difficulty: 3, level: 2, duration: 50, success: 1);

PushClicked

Function prototype:

Telescope.PushClicked(string appversionid = null, bool? cheater = false, string country = null, string firstappversionid = null, int? level = null, string locale = null, string osversionid = null, int? paying_status = null, int? paymentcount = null, int? paymentsum = null, int? sbspaymentcount = null, int? sbspaymentsum = null, int? tag_id = null, bool? tester = false);

Optional Parameters:

  • appversionid:
  • cheater:
  • country:
  • firstappversionid:
  • level:
  • locale:
  • osversionid:
  • paying_status:
  • paymentcount:
  • paymentsum:
  • sbspaymentcount:
  • sbspaymentsum:
  • tag_id:
  • tester:

Example usage:

Telescope.PushClicked(tag_id: 112233);

PushSent

Function prototype:

Telescope.PushSent(string appversionid = null, bool? cheater = false, string country = null, string deviceid = null, string firstappversionid = null, int? level = null, string locale = null, string osversionid = null, int? paying_status = null, int? paymentcount = null, int? paymentsum = null, int? sbspaymentcount = null, int? sbspaymentsum = null, int? tag_id = null, bool? tester = false);

Optional Parameters:

  • appversionid:
  • cheater:
  • country:
  • deviceid:
  • firstappversionid:
  • level:
  • locale:
  • osversionid:
  • paying_status:
  • paymentcount:
  • paymentsum:
  • sbspaymentcount:
  • sbspaymentsum:
  • tag_id:
  • tester:

Example usage:

Telescope.PushSent(tag_id: 112233);

Subscriptions

Function prototype:

Telescope.Subscriptions(string appversionid = null, bool? cheater = false, string country = null, string currency = null, string deviceid = null, string firstappversionid = null, int? level = null, string locale = null, string osversionid = null, int? p21 = null, int? paymentcount = null, string paymentid = null, int? paymentsum = null, string period = null, double? price = null, double? priceusd = null, int? product = null, string sbs_state = null, int? sbspaymentcount = null, int? sbspaymentsum = null, bool? tester = false, int? valid = null);

Optional Parameters:

  • appversionid:
  • cheater:
  • country:
  • currency:
  • deviceid:
  • firstappversionid:
  • level:
  • locale:
  • osversionid:
  • p21:
  • paymentcount:
  • paymentid:
  • paymentsum:
  • period:
  • price:
  • priceusd:
  • product:
  • sbs_state:
  • sbspaymentcount:
  • sbspaymentsum:
  • tester:
  • valid:

Example usage:

Telescope.Subscriptions(valid: 1, currency: "usd", period: "month", price: 9.90);

Tutorials

Function prototype:

Telescope.Tutorials(string appversionid = null, bool? cheater = false, string country = null, string deviceid = null, DateTime? eventtime_daily = null, string firstappversionid = null, int? level = null, string locale = null, string osversionid = null, int? paying_status = null, int? paymentcount = null, int? paymentsum = null, int? sbspaymentcount = null, int? sbspaymentsum = null, int? step = null, bool? tester = false);

Optional Parameters:

  • appversionid:
  • cheater:
  • country:
  • deviceid:
  • eventtime_daily:
  • firstappversionid:
  • level:
  • locale:
  • osversionid:
  • paying_status:
  • paymentcount:
  • paymentsum:
  • sbspaymentcount:
  • sbspaymentsum:
  • step:
  • tester:

Example usage:

Telescope.Tutorials(step: 3, level: 1, tester: true);

CustomOffChainEvents

Function prototype:

Telescope.CustomEvents(string eventName, bool? cheater = false, int? customBooleanProperty1 = null, double? customNumberProperty1 = null, double? customNumberProperty2 = null, string customStringProperty1 = null, string customStringProperty2 = null, string customStringProperty3 = null, bool? tester = false);

Required Parameters:

  • eventName:

Optional Parameters:

  • cheater:
  • tester:
  • customBooleanProperty1:
  • customNumberProperty1:
  • customNumberProperty2:
  • customStringProperty1:
  • customStringProperty2:
  • customStringProperty3:

Example usage:

Telescope.CustomOffChainEvents("double_jump", customBooleanProperty1: 1, customStringProperty1: "2023-01-01T23:00:00Z");