Android Basic Methods

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:

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

  • DevToDevTutorialState.Finish or -2 - instead of the last step number;

  • DevToDevTutorialState.Skipped or 0 - if user skipped the tutorial.

In other cases use step numbers. Make sure you use numbers above 0 to numerate 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.

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

Levelling up

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

/**
* Player has reached a new level
* @param int level - level reached by the player.
*/
DevToDev.levelUp(int 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.

/**
* @param int level - level reached by the player
* @param HashMap resources - hashmap with the currency names and amounts
*/
HashMap resources = new HashMap
Integer>();
resources.put("Currency name 1", 1000);
resources.put("Currency name 2", 10);
DevToDev.levelUp(level, resources);

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

/**
* @param String currencyName - currency name (max. 24 symbols)
* @param float currencyAmount - the amount an account has been credited with
* @param AccrualType accrualType - the way the currency was obtained: earned or purchased
*/
DevToDev.currencyAccrual(currencyName, currencyAmount, accrualType);

AccrualType can take one of the following values:

public enum AccrualType {
                          Earned,
                          Purchased
                        };

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 String paymentId - transaction ID (max. 64 symbols)
* @param float inAppPrice - product price (in user's currency)
* @param String inAppName - product name
* @param String inAppCurrencyISOCode - transaction currency 
* (ISO 4217 format http://www.iso.org/iso/home/standards/currency_codes.htm Exapmle: "USD")
*/
DevToDev.realPayment(String paymentId, float inAppPrice, String inAppName, 
                     String inAppCurrencyISOCode);

How to find the transaction ID in GooglePlay transaction?

Find the INAPP_PURCHASE_DATA object In the JSON fields that are returned in the response data for a purchase order. A unique transaction identifier is the value of orderId property in INAPP_PURCHASE_DATA object. If the order is a test purchase made via the In-app Billing Sandbox, orderId property will be empty.

Attention! devtodev server does not process transactions with previously used transaction IDs. Also, the server validates the identifiers in appearance to avoid evident cheat transactions. To avoid completely the entering of cheat payments from GooglePlay in reports, use devtodev anticheat service before creating realPayment event.

In-app purchases

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

/**
* In-app purchase with a definite article ID.
*
* @param purchaseId - unique purchase Id or name (max. 32 symbols)
* @param purchaseType - purchase type or group (max. 96 symbols)
* @param purchaseAmount - count of purchased goods
* @param purchasePrice - cost of purchased goods (total cost - if several goods were purchased)
* @param purchaseCurrency - currency name (max. 24 symbols)
*/
DevToDev.inAppPurchase(String purchaseId, String purchaseType, int purchaseAmount, 
                       int purchasePrice, String purchaseCurrency);

In case a product was bought for several game currencies at onсe, it is necessary to make a hashmap that includes the names and amounts of the paid currencies.

HashMap resources = new HashMap();
resources.put("currency_1", 120);
resources.put("currency_2", 29);

…and so on…

DevToDev.inAppPurchase(String purchaseId, String purchaseType, int purchaseAmount, HashMap resources);

Custom Events

If you want to count the events that 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 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 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 history of event's usage. 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. 

/**
* Simple custom event
* @param String eventName - event name
*/
DevToDev.customEvent(eventName);

10 parameter names may be associated with any event:

CustomEventParams params = new CustomEventParams();
params.putDouble("double", 1.12);
params.putFloat("float", 9.99f);
params.putInteger("int", 145);
params.putLong("long", 123L);
params.putString("string","start");

Then use method:

/**
* Custom event with params
* @param String eventName - event name
* @param CustomEventParams params - event parameters
*/
DevToDev.customEvent(eventName, params);

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
    /**
    * 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, 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, params);

    LocationEventParams class methods:

    /**
    * Location level of difficulty (optional).
    * @param int difficultyLevel - level of difficulty
    */
    setDifficulty(difficultyLevel);
    
    /**
    * Previously visited location (optional).
    * @param String locationName -  previously visited location name
    */
    setSource(locationName);
    
    /**
    * State/result of the location passing (required).
    * @param boolean isCompleted -  true if location is successfuly passed
    */
    setSuccessfulCompletion(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 int duration - time in seconds
    */
    setDuration(duration);
    
    /**
    * User spendings within the location passing (optional).
    * @ param HashMap<String, Number> spent - user spendings. Key length max. 24 symbols.
    */
    setSpent(spent);
    
    /**
    * User earnings within the location passing (optional).
    * @param HashMap<String, Number> earned - user earnings. Key length max. 24 symbols.
    */
    setEarned(earned);

     

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. 
// Create a parameters object
LocationEventParams params = new LocationEventParams();

// 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", params);

// ... Player passing the location.

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

// The location is passed successfully (required).
params.setSuccessfulCompletion(true);

// 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.
HashMap<String, Number> spent = new HashMap<String, Number>();
spent.put("Turns", 54);
spent.put("Boost Bomb", 1);
spent.put("Extra 5 Turns", 1);
params.setSpent(spent);

// Gamer finished the passing with 3 stars and gained 5 coins and 1200 score.
HashMap<String, Number> earned = new HashMap<String, Number>();
earned.put("Stars", 3);
earned.put("Score", 1200 );
earned.put("Coins", 5);
params.setEarned(earned); 

// The location passing is over (required).
DevToDev.endProgressionEvent("Vilage step 03", params);
Analytics Integration
User profile