The basic methods of devtodev SDK for UE4

Tutorial steps

The event allows 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:

  • -1  (Start) - at the beginning, before the first step is completed;
  • -2  (Finish) - instead of the number of the last step;
  •  0  (Skipped) - in case user skipped the tutorial.

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

Attention! 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.

Blueprint

 
Field Type Description
Step int32  The latest successfully completed tutorial step

Code

// The event allowing to track the stage of tutorial a player is on.
// int32 step - the latest successfully completed tutorial step.

UDevToDevBlueprintFunctionLibrary::TutorialCompleted(int32 step);

Levelling up

You can analyse the distribution of the players over the levels. The event is sent over reaching a new level by a player.

Blueprint

Field Type Description
Level int32  level reached by the player

Code

// Player has reached a new level
// int32 level - level reached by the player.

UDevToDevBlueprintFunctionLibrary::LevelUp(int32 level);

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

Blueprint

 
Field Type Description
Level int32  level reached by the player

Code

// Player has reached a new level
// int32 level - level reached by the player.
// TArray<FAnalyticsEventAttr> Attributes - dictionary with the currency names and amounts

UDevToDevBlueprintFunctionLibrary::LevelUpWithAttributes(int32 level,
                                                         const TArray<FAnalyticsEventAttr>& Attributes);

To track the average amount of in-game currency earned during a level, it is necessary to send a special method "Record Currency Given with Attributes" from Analytics Blueprint Library after each time an in-game account is replenished.

Blueprint

Field Type Description
Game Currency Type FString Currency name (max. 24 symbols)
Game Currency Amount int32 The amount an account has been credited with.
accrualType Enum Can take one of following values: "Earned" or "Purchased"

Code

FAnalytics::Get().GetDefaultConfiguredProvider()->RecordCurrencyGiven(const FString& GameCurrencyType,
                                                   int GameCurrencyAmount,
                                                   const TArray<FAnalyticsEventAttribute>& EventAttrs);

Payment

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

Blueprint

Field type Description
Transaction Id FString Unique transaction ID
In  AppPrice float Product price (in user's currency)
In App Name FString Product name
In App Currency ISOCode FString Transaction currency (ISO 4217 format)

Code

// Register transactions made through the platform's payment system.
// FString transactionId - transaction ID
// float inAppPrice - product price (in user's currency)
// FString inAppName - product name
// FString inAppCurrencyISOCode - transaction currency (ISO 4217 format)

UDevToDevBlueprintFunctionLibrary::RealPayment(const FString& transactionId,
                                               float inAppPrice,
                                               const FString& inAppName,
                                               const FString& inAppCurrencyISOCode);

In-app purchases

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

Blueprint

Notice! If the purchase is done by more than one currency, then the method should be called as many times as many currencies were used, but the amount of purchase should be set only in one of the times. 

Use the method “Record Simple Item Purchase with Attributes” from Analytics Blueprint Library.

 
Field Type Description
Item Id FString Unique purchase Id or name (max. 32 symbols)
Item Quantity int32 Count of purchased goods

Item Id field is the identifier of purchased item, Item Quantity is the amount of purchased item. Attributes array should contain the following obligatory information:

Field Type Description
purchaseType FString Purchase type or group (max. 96 symbols)
purchasePrice int32 Cost of purchased goods (total cost -if several goods were purchased)
purchaseCurrency FString Currency name (max. 24 symbols)

Code

// In-app purchase with a definite article ID.
// FString ItemId - unique purchase Id or name (max. 32 symbols)
// int32 ItemQuantity - count of purchased goods
//
// FString purchaseType - purchase type or group (max. 96 symbols)
// int32 purchasePrice - cost of purchased goods (total cost -if several goods were purchased)
// FString purchaseCurrency - currency name (max. 24 symbols)

FAnalytics::Get().GetDefaultConfiguredProvider()->RecordItemPurchase(const FString& ItemId,
                                                   int ItemQuantity,
                                                   const TArray<FAnalyticsEventAttribute>& Attributes);

 

Custom Events

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

The event must have a unique name and can include up to 10 parameters. The maximum length of the event name is 72 symbols.
Every parameter inside one event must have 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 parameter value is 255 symbols. 

Attention! 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 50000 of unique values for the whole event use 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 analyse 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, in devtodev database it will appear one more parameter in the event with the same name but with different data type. The report building with such parameter will be quite difficult. 

 

Field Type Description
Event Name FString Custom event name

10 parameter names may be associated with any event. Use "Record Event With Attributes". 

Code

FAnalytics::Get().GetDefaultConfiguredProvider()->RecordEvent(const FString& EventName,
                                                 const TArray<FAnalyticsEventAttribute>& Attributes);

Progression event

First of all, the event is used for the 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 which vary during the the location passing.

Developer must use these 2 methods:

1. Method StartProgressionEvent when enetring the location

Blueprint

Field Type Description
locationName FString The name of location user entered
Attributes TArray<FAnalyticsEventAttr> Location parameters

Code

// The method have to be used when entering the location.
// FString locationName  - the name of location user entered.
// TArray<FAnalyticsEventAttr> Attributes - location parameters
UDevToDevBlueprintFunctionLibrary::StartProgressionEvent(const FString& locationName,
                                                         const TArray<FAnalyticsEventAttr>& Attributes);

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

Blueprint

Field Type Description
locationName FString The name of location user left
Attributes TArray<FAnalyticsEventAttr> Location parameters
Earned TArray<FAnalyticsEventAttr> User earnings within the location passing (optional). Key max. length is 24 symbols.
Spent TArray<FAnalyticsEventAttr> User spendings within the location passing (optional). Key max. length is 24 symbols.

Location parameters

 Key Type Description
success bool State/result of the location passing (required).
source FString Previously visited location (optional).
difficulty int32 Location level of difficulty (optional).
duration int32 Time spent in the location (optional).
In case the parameter is not specified by the developer, it will be automatically сalculated as the date difference
between Start Progression Event and End Progression Event method calls.

Code

// The method have to be used when the location passing is over.
// FString locationName  - the name of location user left.
// TArray<FAnalyticsEventAttr> Attributes - location parameters
// TArray<FAnalyticsEventAttr> Earned - user earnings within the location passing (optional)
// TArray<FAnalyticsEventAttr> Spent - user spendings within the location passing (optional).
UDevToDevBlueprintFunctionLibrary::EndProgressionEvent(const FString& locationName,
                                                       const TArray<FAnalyticsEventAttr>& Attributes,
                                                       const TArray<FAnalyticsEventAttr>& Earned,
                                                       const TArray<FAnalyticsEventAttr>& Spent);

Attention! 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 analyse the example of event integration on match3 game with location map:

Player comes to the third location on the map “Village” while following the game map. 
Passing on the first level of difficulty. Before entering this location gamer passed the third location on the map “City”.
.. Player passing the location.
Player finishes passing of the third location on the map “Village”. The location is passed successfully. The passing took 389 seconds.
Gamer finished the passing with 3 stars and gained 70 coins. While the passing gamer used boost and bought extra 5 turns.

Analytics Integration
User profile