com.elevatix.unity.sdk v2.3.1

Elevatix SDK

Table of contents

• Installation
• Configuration
• Initialization
• Track events
• Handle Offers
• Inform about user level and balance
• Testing and troubleshooting
• Complete Api
  • Analytics Client
  • Tracker
  • Offer
  • Offers Dispatcher
  • Pack
  • CostPackage
  • Product

Required dependency

Unity IAP service. Follow this guide to set up

Installation

• Open Unity editor
• Edit -> Project Settings
• Choose "Package Manager"
• Add new "Scoped Registry"
  • Name: Elevatix
  • URL: https://registry.npmjs.org
  • Scope(s): com.elevatix
• Navigate to Window -> Package Manager
• In packages dropdown choose "My registries"
• Select Elevatix SDK and hit install

That concludes the installation of the SDK!

Configuration

Configuration is straightforward and consist only of two steps

Create the Elevatix "Settings file"

Navigate to Assets -> Create -> Elevatix -> Settings file. This action will generate a settings file named "ElevatixSettings.asset" within the "Assets/Resources" folder.

Obtaining the "Application Key":

• Access dev.admin.elevatix.io and log in using your valid credentials.
• Select the "Settings" page from the menu, situated on the left side of the screen.
• Copy the "Application Key" and proceed to paste it into the ElevatixSettings.asset file within the Unity editor.

You have successfully completed the configuration process!

Initialization

Initialize Elevatix during the game startup, specifically in the preloading/loading stage.

using Elevatix;

AnalyticsClient.Init();

Track events

Using Tracker API inform Elevatix about all significant user actions and state changes.

Here is an example of implementation of the initial event that needs to be tracked:

Login tracking sample

using Elevatix;

Tracker.TrackLogin();

Please note that in addition to this, you will also need to implement all other tracking methods as outlined in the Complete Tracker API section

Handle Offers

After an important event happens while playing the game and Elevatix is informed through the Tracking API, Elevatix will then look for a special offer designed for that exact moment. There's a way in which Elevatix tells the game what offer should be shown to the user.

The AnalyticsClient includes an object named OffersDispatcher. This object has method RegisterHanlder that accepts implementation of OfferHandlerBase<T> where T is SingleOffer or MultiOffer.

using Elevatix;
using Elevatix.Offers;

class SingleOfferHandler : OfferHandlerBase<SingleOffer> {
    protected override Task HandleAsync(SingleOffer offer)
    {
        // show dialog with the single offer
    }
}

class MultiOfferHandler : OfferHandlerBase<MultiOffer> {
    protected override Task HandleAsync(MultiOffer offer)
    {
        // show dialog with multiple purchase options
    }
}

// somewhere during start
AnalyticsClient.OffersDispatcher
    .RegisterHandler(new SingleOfferHandler())
    .RegisterHandler(new MultiOfferHandler())
    .Start();

It's necessary to call Start for letting SDK know that game is ready to start handling offers

Inform about user level and balance

There are two compelling reasons why Elevatix requires access to players' product balances and level state:

• Firstly: This information serves as a crucial safeguard, preventing Elevatix from suggesting non-consumable items that the user has already purchased.
• Secondly: It enables Elevatix to make more informed and strategic choices when determining which product(s) should be recommended to the user, thereby enhancing the overall user experience.

Important Note: It is imperative that all AnalyticsClient.SetInventoryItem and AnalyticsClient.SetLevel calls are executed prior to the first Tracker call. This sequence is critical for ensuring the accuracy and effectiveness of the tracking process.

For instance, consider the following scenario: \ Given that the user has 300 coins (a form of soft in-game currency, identified as ID - 10) and is at level 15. \ The corresponding code should look following:

using Elevatix;

// 10 - Elevatix, product ID
// 300 - is amount of that product
AnalyticsClient.SetInventoryItem(10, 300);
AnalyticsClient.SetLevel(15);

Testing and Troubleshooting

Once the SDK has been successfully integrated and thoroughly tested within the Unity Editor, there may arise a need to conduct testing on a development or test-flight build of the game. \ In such instances, the game must provide a mechanism to expose the Elevatix user ID to the developer. \ This user ID can be obtained by invoking the AnalyticsClient.GetUserId function.

Complete Api

Analytics Client Class

AnalyticsClient is static class and is part of Elevatix namespace.

AnalyticsClient.Init

Parameter: bool(default - true) - Whether the game is activating offers for a specific player \ Description: Initializes SDK

AnalyticsClient.OffersDispatcher

Description: instance of the OffersDispatcher

AnalyticsClient.UserDataService

Description: instance of the UserDataService

AnalyticsClient.Disable

Description: Deactivates all event tracking and offers functionalities

AnalyticsClient.Enable

Description: Activates event tracking and offers features

AnalyticsClient.AreOffersEnabled

Description: Responds to the inquiry regarding the status of Elevatix offers, which can be either enabled or disabled through the administrative application. This determination can only be ascertained once the Elevatix SDK has been initialized

AnalyticsClient.SetLevel

Parameter: long - level of the user \ Description: Provides Elevatix with information regarding the current state of the player's level

AnalyticsClient.SetInventoryItem

Parameter: long - The Elevatix product identifier corresponding to the product owned by the user \ Parameter: long - The quantity of this product available in the user's balance \ Description: Communicates the current state of the player's balance to Elevatix

AnalyticsClient.GetUserId

Description: The method for obtaining the UserID that Elevatix employs for client identification

AnalyticsClient.GetAssetUrls

Description: Returns a list of image URLs utilized in offers. This function is intended to be invoked during the asset loading phase to facilitate the caching of all images

Tracker Class

Tracker is static class and is part of Elevatix namespace.

Tracker.TrackLogin

Description: Should be used after player is logged in

Tracker.TrackEnterMainScreen

Description: Should be used when when player enters main screen(a.k.a home screen)

Tracker.TrackLevelStart

Parameter: int - Level that player started \ Description: Should be used when player enters level

Tracker.TrackLevelWin

Parameter: int - Level that player won \ Description: Should be used when player wins level

Tracker.TrackLevelFail

Parameter: int - Level that player failed \ Description: Should be used after player fails level

Tracker.TrackOfferPurchase

Parameter: long - Offer id that player bought \ Parameter: long - Pack id that player bought \ Description: Should be used after player bought product from offer provided by the Elevatix

Tracker.TrackProductRestore

Parameter: string - Product that been restored, typically it looks like - com.{your-company}.{productId} \ Parameter: List<PurchasedItem> - List of PurchasedItem that represents goods that player got \ Description: Should be used when player restores(without additional charges) product purchase

Tracker.TrackProductRestore

(DEPRECATED) in favor of two parameters method \ Parameter: string - Product that been restored, typically it looks like - com.{your-company}.{productId} \ Description: Should be used when player restores(without additional charges) product purchase

Tracker.TrackCustomPurchase

Parameter: string - Product that been restored, typically it looks like - com.{your-company}.{productId} \ Parameter: List<PurchasedItem> - List of PurchasedItem that represents goods that player got \ Description: Should be used when player made product purchase

Tracker.TrackCustomPurchase

(DEPRECATED) in favor of two parameters method \ Parameter: string - Product that been restored, typically it looks like - com.{your-company}.{productId} \ Description: Should be used when player made product purchase

Tracker.TrackCustomRollingPurchase

Parameter: string - Product that been bought from the store, typically it looks like - com.{your-company}.{productId} \ Parameter: List<PurchasedItem> - List of PurchasedItem that represents goods that player got \ Parameter: int - Index of product in rolling offer chain \ Description: Should be used when player bought something via game owned rolling offers

Tracker.TrackBalanceUpdate

Parameter: string - ID of the updated product \ Parameter: long - Amount of given(positive number) or taken away(negative number) products \ Description: Should be used after players balance has changed

Tracker.TrackAdEvent

Parameter: AdType - type of advertisement (imported from Elevatix.Advertisement namespace)\ Description: should be tracked after ad complete

Tracker.TrackCustomEvent

Parameter: string - event name \ Description: Should be used to track custom event

Offer

Is high level entity that comes to the game. \ Acts as container for the

public class Offer
    {
        // Offer Id
        public long Id;
    }

SingleOffer

Is offer with exact one pack that user can purchase

public class SingleOffer: Offer
    {
        // Pack entity
        public Pack Pack;
    }

MultiOffer

Is offer with more than one pack that user can purcase

public class MultiOffer: Offer
    {
        // Pack entity
        public Packs List<Pack>;
    }

Offers Dispatcher

Object that informs game about offers that game should show for the user. \ Analytics client has includes instance of this object

OffersDispatcher.RegisterHandler

Description: Method that registers specific handler for further offers processing \ Parameter: handler, implementation of the OfferHandlerBase

OffersDispatcher.Start

Description: Tells dispatcher to "start" dispatching offers Returns: Task that is resolved when initial offers are resolved

Pack

Entity containing products for the user, along with pertinent instructions on how to facilitate its sale.

public class Pack
{
    public long Id => id;
    
    // The name of the pack, intended for client-facing display to the user
    public string Name;
    
    // Field contains information about how to sell particular pack 
    public CostPackage CostPackage;
    
    // A list of the products contained within this pack, essentially items to be used as rewards after purchase
    public List<Product> Products;
    
    // The type of the pack, with possible values being PackType.Regular and PackType.Subscription
    public PackType Type;
    
    // Relevant only for PackType.Subscription, representing units of duration
    public DurationType DurationType;
    
    // Relevant only for PackType.Subscription, indicating the duration for which the subscription should be applied
    public int Duration;
    
    // Custom keys and values that are filled in during pack creation
    // Could be usefull for customization of specific pack 
    public Dictionary Meta;
    
    // A URL pointing to the image assigned to the pack
    public string? ImageUrl;
}

Cost Package

It's easier to think of the Cost Package as similar to a 'Price Tag' in a retail store.

public class CostPackage
    {
        // Product id from the store. Should be used to show the price and execute purchase
        public string ProductId;
    }

Product

public class Product
{
    // Identifier for the product, consistent with its use in TrackBalanceUpdate and SetInventoryItem. 
    // Particularly necessary for awarding users
    public long Id;

    // The name of the product
    public string Name;

    // A flag set from the admin application. Used to identify the product's category and may require custom logic
    public bool Special;

    // Either "HARD" or "SOFT." This field allows for custom logic based on these two categories
    public string CurrencyType;

    // Either "CONSUMABLE" or "NON_CONSUMABLE." This field allows for custom logic based on these two categories
    public string ConsumeType;

    // Quantity of products in the parent pack
    public int Quantity;
    
    // Custom string of the product assigned during pack creation in the admin app
    public string CustomProperty;

#nullable enable

    // Image associated with the specific product in the "Elevatix Settings" file
    public Sprite? Image;

    // String associated with the specific product in "Elevatix Settings".
    // It might be used to display the sprite image with rich text
    public string? Sprite;

    // URL pointing to the image assigned to the product
    public string? ImageUrl;

#nullable disable
}

PurchasedItem

Entity that represents goods that user received as one of rewards to purchase.

  class PurchasedItem {
      
      /// <summary>
      /// Entity that represents goods that user received as one of rewards to purchase
      /// </summary>
      /// <param name="productId">Product Identifier registered in elevatix admin app</param>
      /// <param name="amount">Amount for items granted to the user</param>
      /// <param name="customProperty">Custom value of that most likely would be some kind of "type"</param>
      public PurchasedItem(long productId, double amount, string customProperty = null)
  }

UserDataService

Object for defining player data. Instantiated in the AnalyticsClient.UserData field

SetRegistrationDate

!Important note: This method should be called before AnalyticsClient.Init call, otherwise is ignored Description: Notifies Elevatix about user registration date \ Parameter: long timestamp of the moment when user got registered or installed the app