My AppsLive demoNewsArticles

Basic methods

Please take a look at our Expert tips before integrating the events.

Onboarding (tutorial)

The Tutorial steps event allows you to evaluate the effectiveness of the tutorial steps system. The event should be sent at the end of each tutorial step indicating the number of every passed step as a parameter.

Use the following constants to specify basic events of tutorial steps:

  • Start or -1 - at the beginning, before the first step is completed;

  • Finish or -2 - instead of the final step number;

  • Skipped or 0 - in case а user skipped the tutorial.

In other cases use step numbers. Make sure you use numbers above 0 to enumerate the steps.

The logic of the use of the Skipped constant in the Tutorial steps event is provided only in case a user has completely refused to pass the tutorial. After Skipped is used, no other values of the Tutorial steps event must be received. 

/**
* The event allowing to track the stage of tutorial a player is on.
* @param NSUInteger tutorialStep - the latest successfully completed tutorial step.
*/
[DevToDev tutorialCompleted: (NSUInteger) tutorialStep];

Leveling up

This event is for games only.

You can analyze the distribution of the players over the levels. The event should be sent right after the player reached the next level. You can find more information on what is the right moment to use LevelUp event here.

/**
* Player has reached a new level
* @param NSInteger level - level reached by the player.
*/
[DevToDev levelUp: (NSInteger) level];

To track the average account balance of in-game currency by the end of each level, please provide the list of currency names and amounts.

/**
* Player has reached a new level
* @param NSInteger level - level reached by the player.
* @param NSDictionary resources - dictionary with the currency names and amounts
*/
NSDictionary * resources = @{@"Currency name 1" : @100, @"Currency name 2" : @10};
[DevToDev levelUp: (NSUInteger) level withResources: withResources: (NSDictionary *) resources];

To track the average amount of in-game currency earned during a level, it is necessary to send a special event after each time an in-game account is replenished.

/* *
* @param NSString * currencyName - currency name (max. 24 symbols)
* @param NSInteger amount - the amount an account has been credited with.
* @param AccrualType accrualType - the way the currency was obtained: earned or purchased
*/
[DevToDev currencyAccrual: (NSInteger) amount withCurrencyName: (nonnull NSString *) currencyName
 andCurrencyType: (AccrualType) accrualType];

AccrualType can take one of the following values:

typedef enum {
Earned,
Purchased
} AccrualType ;

Real-World Currency Payment

To track payments, add this event right after the platform confirms that a payment went through.

/**
* Register transactions made through the platform's payment system.
*
* @param NSString * paymentId - transaction ID  (max. 64 symbols)
* @param float inAppPrice - product price (in user's currency)
* @param NSString * inAppName - product name
* @param NSString * inAppCurrencyISOCode - transaction currency (ISO 4217 format)
*/
[DevToDev realPayment: (NSString *) transactionId withInAppPrice:(float) inAppPrice 
andInAppName: (NSString *) inAppName andInAppCurrencyISOCode: (NSString *) inAppCurrencyISOCode];

A unique order identifier is a value of a transactionIdentifier property in SKPaymentTransaction object inside the receipt of completed transaction.

devtodev server does not process transactions with previously used transaction IDs. Also, the server validates identifiers in appearance to avoid evident cheat transactions. To avoid adding cheat payments into reports completely, use devtodev anti-cheat service before creating a realPayment event.

Virtual Currency Payment

This event is for games only.

To track expenditures of in-game currency and popularity of products, add this event right after the purchase.

/**
* In-app purchase with a definite article ID.
*
* @param NSString purchaseId - unique purchase Id or name (max. 32 symbols)
* @param NSString purchaseType - purchase type or group (max. 96 symbols)
* @param NSInteger purchaseAmount - count of purchased goods
* @param NSInteger purchasePrice - cost of purchased goods (total cost -if several goods were purchased)
* @param NSString purchaseCurrency - currency name (max. 24 symbols)
*/
[DevToDev inAppPurchase: (NSString *) purchaseId withPurchaseType: (NSString *) purchaseType 
andPurchaseAmount: (NSInteger) purchase Amount andPurchasePrice: (NSInteger) purchaseprice 
andPurchaseCurrency: (NSString *) purchaseCurrency];

In case a product is bought for several game currencies at once, it is necessary to make a dictionary that includes the names and amounts of the paid currencies.

NSMutableDictionary * resources = [[NSMutableDictionary alloc] init];
[resources setObject:@100 forKey:@"currency1"];
[resources setObject:@10 forKey:@"currency2"];
//...and so on...

[DevToDev inAppPurchase:(NSString )purchaseId withPurchaseType:(NSString )purchaseType
 andPurchaseAmount:(NSInteger)purchaseAmount andResources: (NSDictionary *) resources];

Please keep in mind that there is a limit for the number of unique values of the "purchaseCurrency" parameter - 30 currencies per project. Currencies cannot be deleted or renamed.

Custom Events

If you want to count the events that are not among basic, use custom events.

Attention! We strongly recommend that you do not use custom event properties to transfer and store data that fits the definition of personal data!

The event must have a unique name and can include up to 20 parameters. The maximum length of the event name is 72 symbols.

Every parameter inside one event must have a unique name. The maximum length of the parameter name is 32 symbols.

The values of parameters can be string or number type (int, long, float, double). The maximum length of the parameter value is 255 symbols.

No more than 300 variants of custom event names can be used for one project. Try to enlarge events in meaning by using event parameters. Events that didn't get into the limit of unique event names will be discarded.

For a string parameter, it is acceptable to use not more than 50,000 unique values for the whole event history. In case the limit of unique values is exceeded, the parameter is ignored.

Therefore, we recommend not to set user IDs and Unix time as parameter values of custom events. Try to integrate parameter values if they have a very large variability. Otherwise, it will be very difficult to analyze the data or after some time it may be even ignored.

We strongly recommend not to change the type of data transferred in the parameter over time. In case you change the data type in parameter, it will be duplicated with the same name and different data types in devtodev database which will result in more complicated report building.

/**
* @param NSString eventName - event name
*/
[DevToDev customEvent: (NSString *) eventName];

20 parameter names may be associated with any event:

CustomEventParams * params_1 = [[CustomEventParams alloc] init];
[params_1 putParam:@"double" withDouble:123.1231231231231];
[params_1 putParam:@"float" withFloat:123.123123f];
[params_1 putParam:@"int" withInt:123];
[params_1 putParam:@"long" withLong:6152437L];
[param_1 putParam:@"string" withString:@"string"];

Then use method:

/**
* @param NSString eventName - event name
* @param CustomEventParams params - event parameters
*/
[DevToDev customEvent: (NSString *) eventName withParams: (CustomEventParams *) params];

Progression event

This event is for games only.

First of all, a Progression event is used for games with short (within one game session) locations/game levels. The event allows you to gather data on passing the locations and get statistics on parameters that vary during the location passing.

Developer must use the following two methods:

  1. Method startProgressionEvent when entering the location:

    /**
* The method have to be used when entering the location.
* @param String locationName - the name of location user entered.
* @param LocationEventParams params - instance of location parameters class
*/
[DevToDev startProgressionEvent: locationName withParameters: params];

  2. Method endProgressionEvent when exiting (no matter if completed or not) the location:

    /**
* The method have to be used when the location passing is over.
* @param String locationName - the name of location user left.
* @param LocationEventParams params - instance of location parameters class
*/
[DevToDev endProgressionEvent: locationName withParameters: params];

    LocationEventParams class methods:

      /**
  * Location level of difficulty (optional).
  * @param NSInteger difficultyLevel - level of difficulty
  */
  [params setDifficulty: difficultyLevel];

  /**
  * Previously visited location (optional).
  * @param NSString* locationName -  previously visited location name
  */
  [params setSource: locationName];

  /**
  * State/result of the location passing (required).
  * @param BOOL isCompleted -  true if location is successfuly passed
  */
  [params setIsSuccess: isCompleted];

  /**
  * Time spent in the location (optional).
  * In case the parameter is not specified by the developer, it will be automatically calculated
  * as the date difference between startProgressionEvent and endProgressionEvent method calls.
  * @param NSNumber* duration - time in seconds
  */
  [params setDuration: duration];

  /**
  * User spendings  within the location passing (optional).
  * @ param NSDictionary* spent - user spendings. Key length max. 24 symbols.
  */
  [params setSpent: spent];

  /**
  * User earnings  within the location passing (optional).
  * @param NSDictionary* earned - user earnings. Key length max. 24 symbols.
  */
  [params setEarned: earned];

The user can be only in one location at the same time. When moving to another location (including embedded), the previous location must be completed. Information on locations, the passing of which was not completed by calling endProgressionEvent method during the game session (the call of endProgressionEvent method is not integrated; user unloaded the application from the device memory; there was an application crash), do not fall in the statistics.

Let’s look at the example of event integration for a match3 game with a location map:

// Player comes to the third location on the map "Village" while following the game map. 
// Create a parameters object
LocationEventParams* params = [[LocationEventParams alloc] init];

// Specify the known location parameters:
// Passing on the first level of difficulty.
[params setDifficulty:1];

// Before entering this location gamer passed the third location on the map “Village” (optional).
[params setSource: @"Vilage step 02"];

//The location passing starts (required).
[DevToDev startProgressionEvent:@"Vilage step 03" withParameters:params];

// ... Player passing the location.

// Player finishes passing of the third location on the map “Village”

// The location is passed successfully (required).
[params setIsSuccess: YES];

// The passing took 189 seconds.
[params setDuration:@189];

// Location is passed for 54 turns. While the passing gamer used boost and bought extra 5 turns.
NSDictionary* spent = @{
    @"Turns" : @54,
    @"Boost Bomb" : @1,
    @"Extra 5 Turns" : @1
};
[params setSpent: spent];

// Gamer finished the passing with 3 stars and gained 5 coins and 1200 score.
NSDictionary* earned = @{
    @"Stars" : @3,
    @"Score" : @1200,
    @"Coins" : @5
};
[params setEarned: earned]; 

// The location passing is over (required).
[DevToDev endProgressionEvent: @"Vilage step 03" withParameters: params];
PreviousSetting up EventsNextSecondary methods

Last updated

#989: best practices - improved readability

Change request updated