.. This file was automatically generated by RstDoclet. Do not touch. .. _Tracker: Tracker ======= This class is used to track analytics events. This cannot be used unless the SDK has already been initialized. See :ref:`setup`. Public methods -------------- track(String eventName [, Map 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 .. code-block:: java Tracker.track("custom_name", withExtras("param1", "value1") .and("param2", 420)); ---------- trackInstall( [, Map extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Indicates a first-time launch of the app. .. admonition:: 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 extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ DEPRECATED Indicates that the user has been enrolled into a variant that is part of an A/B test. .. admonition:: 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 extras, Map extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Indicates that the app has entered the foreground and become active. .. admonition:: 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 extras, Map extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Indicates that the app has entered the foreground and become active. .. admonition:: 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 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. .. admonition:: 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 items [, Map extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sent when the user performs any economic transaction using virtual currencies or goods. .. admonition:: 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: .. code-block:: java 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: .. code-block:: java 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. .. admonition:: 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 .. code-block:: java 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 .. code-block:: java trackPayment(withAmountUS(5.99) .error("Something really bad happened") .special("fire", "Fire Balls") .storeSku("fire_balls")); ---------- trackRegistration(String email, String type, boolean isNew [, Map extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sent whenever the user registers an account with the game's backend. .. admonition:: 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 extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sent whenever the user encounters a failure on registering an account with the game's backend. .. admonition:: 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 extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Represents a player's invitation to other parties to promote the game. .. admonition:: 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 extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Represents the presentation of a promotion, sale, or event to the user. .. admonition:: 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 extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Represents the player's earning of an achievement. .. admonition:: 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 extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Represents the player's earning of an achievement. .. admonition:: 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 extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sent when a player connects to a 3rd party authenticator. .. admonition:: 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+ .. code-block:: java 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: .. code-block:: java Tracker.trackConnect("GameCircle", null, null, null, null, null, null, null, "12312"); ---------- trackAd(AdEvent adEvent, boolean isBackfill, String adFailureReason, String adNetwork, AdType adType [, Map extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is for requests to ad networks for ads. .. admonition:: 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 extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Tracks an ad controller. .. admonition:: 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 extras]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Sent when the user graduates from one experience level to the next. The exact meaning of a level is game-specific. .. admonition:: 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`. .. code-block:: java 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"}`` .. code-block:: java 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: .. code-block:: java 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: .. code-block:: java 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: .. code-block:: java import static com.scopely.analytics.Tracker.trackPayment; import static com.scopely.analytics.Tracker.withAmountUs; ... trackPayment(withAmountUs(460).storeSku("someItem")); .. seealso:: :doc:`Transactions`