Tracker

This class is used to track analytics events. This cannot be used unless the SDK has already been initialized. See SDK setup.

Public methods

track(String eventName [, Map<String, Object> extras])

Tracks a custom event

  • eventName name of the event to track
  • extras (optional) map of extra properties

Example

Tracks a custom event using custom extras

Tracker.track("custom_name", withExtras("param1", "value1")
                                   .and("param2", 420));

trackInstall( [, Map<String, Object> extras])

Indicates a first-time launch of the app.

Context

This should be sent at the same time that the install_time device property is set. It seems redundant with that property, but this gives our analysts an event to key off of in their queries, which is useful to them. This event is also triggered automatically when a device is first registered.

  • extras (optional) use this to send extra information in this event

trackAbTest(String testName, String variant [, Map<String, Object> extras])

DEPRECATED

Indicates that the user has been enrolled into a variant that is part of an A/B test.

Context

This should be sent at the time that the user’s variant membership changes.

  • testName The name of the A/B test which contains variants.
  • variant The variant within the test that the current user is now a member of. If you are using Scopely’s experiments system, this event is not needed and should not be sent.
  • extras (optional) use this to send extra information in this event

trackAppOpen(String level [, Map<String, Object> extras, Map<String, Object> extras])

Indicates that the app has entered the foreground and become active.

Context

Should be sent every time the app enters the foreground.

  • level current level user at the moment of opening the app
  • extras (optional) use this to send extra information in this event
  • extras (optional) use this to send extra information in this event

trackAppOpen( [, Map<String, Object> extras, Map<String, Object> extras])

Indicates that the app has entered the foreground and become active.

Context

Should be sent every time the app enters the foreground.

  • extras (optional) use this to send extra information in this event
  • extras (optional) use this to send extra information in this event

trackFirstTimeExperienceFlow(int step, boolean complete, boolean skipped, int duration [, Map<String, Object> extras])

Sent once for each step of the first time experience that a user progresses through, where the step parameter is incremented at each step along the way.

Context

Should be sent each time the user completes one of the game’s FTE flow steps.

  • step An integer representing which step in the sequence of the FTE flow the user has just completed.
  • complete true to indicate that this is the final step of the FTE flow. false otherwise. Eventually you should always send an event with this parameter set to true, even if you need to send it after the user has skipped or otherwise gone around the final step.
  • skipped true if skipped
  • duration The time, in seconds, that the user spent on this step.
  • extras (optional) use this to send extra information in this event

trackGameTransaction(String transactionType, String context, String id, List<Transaction> items [, Map<String, Object> extras])

Sent when the user performs any economic transaction using virtual currencies or goods.

Context

Sent every time the user performs a transaction with virtual currencies or goods.

  • transactionType One of: “Buy”, “Sell”, “Use”, or a game-specific reason such as “TournamentEnd”.
  • context additional information for this transaction
  • id transaction ID
  • items a list of items in this transaction
  • extras (optional) use this to send extra information in this event

Examples

Track a transaction where user buys a scratch using 10 coins:

trackGameTransaction("Buy", "Buy scratch", null,
                     withTransactions("scratch", 1).and("coins", -10));

User buys 5 poison, 1 hat using 25 diamonds, new diamond balance is 75. The transaction was assigned ID ph-1231 by the game backend:

trackGameTransaction("Buy", "Death Market", "ph-1231",
                     withTransactions("diamonds", -25, 75)
                                 .and("poison", 5, 10)
                                 .and("hat", 1, 1),
                     withExtras("orange", "juice"));

trackPayment(PaymentInfo paymentInfo)

Sent when the user purchases anything with real money from any of the stores.

Context

Sent at the time that a purchase attempt is completed, whether successful or not.

  • paymentInfo contains information about the payment being tracked.

Examples

Track successful payment of 3.99USD for Free Spanks commodity

trackPayment(withAmountUS(399) // 3.99 USD
             .amountLocal(7000)
             .localCurrencyType("COP")
             .special("free_spanks", "Free spanks")
             .storeSku("free_spanks_sku")
             .gameSku("free_death_spanks")
             .paymentId("1000213.442311")); // ID assigned by Google Play

Track unsuccessful payment of 5.99USD for Fire Balls

trackPayment(withAmountUS(5.99)
             .error("Something really bad happened")
             .special("fire", "Fire Balls")
             .storeSku("fire_balls"));

trackRegistration(String email, String type, boolean isNew [, Map<String, Object> extras])

Sent whenever the user registers an account with the game’s backend.

Context

Sent at the time that the registers with the game as a persistent account; if there is an anonymous or guest mode, this event should not be fired until some registration or identity association process has been completed. This may or may not be at the same time that the user links with social networks.

  • email The player’s email address, if provided as part of the game’s registration. His email as derived from linking to social networks is not included on this event. (The “connect” event will reflect those, instead).
  • type One of: “Email”, “Facebook”, “GooglePlay”, or a custom string identifying the identifier used to register the player.
  • isNew true to indicate that the user’s registration seemed to be a new user for whom a new account was created or false to indicate that the user’s existing account was found and linked on the game’s backend.
  • extras (optional) use this to send extra information in this event

trackRegistrationFailure(String email, String type, String error [, Map<String, Object> extras])

Sent whenever the user encounters a failure on registering an account with the game’s backend.

Context

Sent at the time that the registers with the game as a persistent account; if there is an anonymous or guest mode, this event should not be fired until some registration or identity association process has been completed. This may or may not be at the same time that the user links with social networks.

  • email The player’s email address, if provided as part of the game’s registration. His email as derived from linking to social networks is not included on this event. (The “connect” event will reflect those, instead).
  • type One of: “Email”, “Facebook”, “GooglePlay”, or a custom string identifying the identifier used to register the player.
  • error The error code should match the game’s own backend error codes for registration failures. If none exists, then succinct strings can be used instead.
  • extras (optional) use this to send extra information in this event

trackViral(String type [, Map<String, Object> extras])

Represents a player’s invitation to other parties to promote the game.

Context

Sent at the time that the player causes invitations or promotions to be sent out by any medium.

  • type A succinct string stating the channel that was used. e.g. “SMS”, “Email”, “FacebookInvite”, “FacebookPost”, etc.
  • extras (optional) use this to send extra information in this event

trackPromo(String action, String type, String promoId [, Map<String, Object> extras])

Represents the presentation of a promotion, sale, or event to the user.

Context

Sent at the time the user is presented with a promo in the game’s UI and the user takes some action on that presentation.

  • action A succinct string stating the user’s response to the promo. e.g. “Accept”, “Cancel”.
  • type A succinct string to identify what type of promo it is e.g. “Sale”, “Virality”, “Events” etc.
  • promoId A unique identifier for the promo being displayed
  • extras (optional) use this to send extra information in this event

trackAchievement(String achievementId, String title [, Map<String, Object> extras])

Represents the player’s earning of an achievement.

Context

Sent at the moment the player is awarded an achievement.

  • achievementId A unique identifier for the achievement earned.
  • extras (optional) use this to send extra information in this event

trackAchievement(String achievementId, String title, String system [, Map<String, Object> extras])

Represents the player’s earning of an achievement.

Context

Sent at the moment the player is awarded an achievement.

  • achievementId A unique identifier for the achievement earned.
  • system Name of the standard achievement system this was in (GooglePlay or GameCircle). Null if none.
  • extras (optional) use this to send extra information in this event

trackConnect(String connection, String firstName, String lastName, Gender gender, Integer birthYear, Integer birthMonth, Integer birthDay, String email, String id [, Map<String, Object> extras])

Sent when a player connects to a 3rd party authenticator.

Context

Sent at the moment that a user successfully connects to a 3rd party. This means, for example, we have received a token and/or success response from the 3rd party. Note that the birthday is set with all the information available, which might be month and day, year and month, or just year. Unknown parts should be set to null.

  • connection The name of the 3rd party. One of: “Facebook”, “Google+”, “GameCenter”, “GameCircle”, or a custom string.
  • firstName (optional) The user’s first name according to the 3rd party
  • lastName (optional) The user’s last name according to the 3rd party
  • gender (optional) The user’s gender according to the 3rd party.
  • birthYear (optional) Birth year.
  • birthMonth (optional) Birth month
  • birthDay (optional) Birth day
  • email (optional) Email if provided by third party
  • id (optional) ID in the third party’s system
  • extras (optional) use this to send extra information in this event

Examples

User signed in with Google+

Tracker.trackConnect("Google+", "Rick", "Hickey",
                     Gender.MALE, 1973, 1, 10, "rick@example.com", "12312");

User signed in with GameCircle and we have no name, just a user ID from their system:

Tracker.trackConnect("GameCircle", null, null,
                     null, null, null, null, null, "12312");

trackAd(AdEvent adEvent, boolean isBackfill, String adFailureReason, String adNetwork, AdType adType [, Map<String, Object> extras])

This is for requests to ad networks for ads.

Context

Keep in mind that the banner and interstitial controllers do double duty. When they are requesting ads to show this event should fire. When they are figuring out where to go in the waterfall ad_controller event should fire.

  • adEvent the ad event type
  • isBackfill true if ad is backfill, otherwise false. Backfill means that we are loading because the primary ad was not ready. Rubicon is only backfill if loading in the context of no ad. If Rubicon appeared naturally in the waterfall isBackfill should be null because its a normal ad provider.
  • adFailureReason reason for ad failure (if adEvent was FAILURE)
  • adNetwork network name lowercase, adcolony, admob, chartboost, etc
  • adType “banner” or “interstitial”
  • extras (optional) use this to send extra information in this event

trackAdController(AdEvent adEvent, String adFailureReason, String adNetwork, AdType adType [, Map<String, Object> extras])

Tracks an ad controller.

Context

called when the banner or interstitial controllers phone home to the ads sdk to figure out what ad network to load next in the waterfall

  • adEvent the ad event type
  • adFailureReason reason for ad failure (if adEvent was FAILURE)
  • adNetwork “n/a” - for request and failure, otherwise network name lowercase, adcolony, admob, chartboost, etc that is next in waterfall
  • adType “banner” or “interstitial”
  • extras (optional) use this to send extra information in this event

trackLevelUp(String previousLevel, String level [, Map<String, Object> extras])

Sent when the user graduates from one experience level to the next. The exact meaning of a level is game-specific.

Context

Sent every time the player reaches a new level.

  • previousLevel The player’s level before leveling up.
  • level The player’s new level.
  • extras (optional) use this to send extra information in this event

Example

User reached level SuperExpert from level KindaGood.

Tracker.trackLevelUp("KindaGood", "SuperExpert");

trackAirshipRegister(String channelId)

Sent when Urban Airship registration completes.

Airship registration tracking should generally be done automatically; the SDK should auto-detect.

  • channelId Tolerates nulls, but will not be tracked when null.

withExtras(String key, Object val)

Use this method to fluently append extras to a tracking method.

Example

Track custom events with extras {foo: 1, bar: "qux"}

import static com.scopely.analytics.Tracker.withExtras;

...

Tracker.track("event_name", withExtras("foo", 1).and("bar", "qux"));

withTransactions(String itemName, int itemQuantity [, int balance])

Use this method to fluently create lists of transactions with balance

  • itemName the name of the transacted item
  • itemQuantity how many items are being transacted
  • balance (optional) specify the balance of the item after the transaction

Examples

User buys a scratch using 10 coins:

import static com.scopely.analytics.Tracker.trackGameTransaction;
import static com.scopely.analytics.Tracker.withTransactions;

...

trackGameTransaction("Buy", "Buy scratch",
                     withTransactions("scratch", 1).and("coins", -10));

User buys a scratch using 10 coins and ends up without money:

import static com.scopely.analytics.Tracker.trackGameTransaction;
import static com.scopely.analytics.Tracker.withTransactions;

...

trackGameTransaction("Buy", "Buy scratch",
                     withTransactions("scratch", 1, 1).and("coins", -10, 0));

withAmountUS(int usdCents)

Use this method to fluently create a payment information instance. Keep in mind that the amount in USD must be in cents.

  • usdCents amount of USD cents

Example

User buys a scratch using 10 coins:

import static com.scopely.analytics.Tracker.trackPayment;
import static com.scopely.analytics.Tracker.withAmountUs;

...

trackPayment(withAmountUs(460).storeSku("someItem"));

See also

Transactions