Table of contents
- Installation
- Configuration
- Initialization
- Track events
- Handle Offers
- Inform about user level and balance
- Testing and troubleshooting
- Complete Api
Unity IAP service. Follow this guide to set up
- 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
Configuration is straightforward and consist only of two steps
Navigate to Assets -> Create -> Elevatix -> Settings file. This action will generate a settings file named "ElevatixSettings.asset" within the "Assets/Resources" folder.
- 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!
Initialize Elevatix during the game startup, specifically in the preloading/loading stage.
using Elevatix;
AnalyticsClient.Init();
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:
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
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
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);
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.
AnalyticsClient
is static class and is part of Elevatix
namespace.
Parameter: bool
(default - true
) - Whether the game is activating offers for a specific player
Description: Initializes SDK
Description: instance of the OffersDispatcher
Description: instance of the UserDataService
Description: Deactivates all event tracking and offers functionalities
Description: Activates event tracking and offers features
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
Parameter: long
- level of the user
Description: Provides Elevatix with information regarding the current state of the player's level
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
Description: The method for obtaining the UserID that Elevatix employs for client identification
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
is static class and is part of Elevatix
namespace.
Description: Should be used after player is logged in
Description: Should be used when when player enters main screen(a.k.a home screen)
Parameter: int
- Level that player started
Description: Should be used when player enters level
Parameter: int
- Level that player won
Description: Should be used when player wins level
Parameter: int
- Level that player failed
Description: Should be used after player fails level
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
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
(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
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
(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
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
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
Parameter: AdType
- type of advertisement (imported from Elevatix.Advertisement namespace)
Description: should be tracked after ad complete
Parameter: string - event name
Description: Should be used to track custom event
Is high level entity that comes to the game.
Acts as container for the
public class Offer
{
// Offer Id
public long Id;
}
Is offer with exact one pack that user can purchase
public class SingleOffer: Offer
{
// Pack entity
public Pack Pack;
}
Is offer with more than one pack that user can purcase
public class MultiOffer: Offer
{
// Pack entity
public Packs List<Pack>;
}
Object that informs game about offers that game should show for the user.
Analytics client has includes instance of this object
Description: Method that registers specific handler for further offers processing
Parameter: handler, implementation of the OfferHandlerBase
Description: Tells dispatcher to "start" dispatching offers Returns: Task that is resolved when initial offers are resolved
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;
}
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;
}
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
}
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)
}
Object for defining player data. Instantiated in the AnalyticsClient.UserData
field
!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