Follow

Integrating the Apmetrix Android (Java) SDK

 

Table of Contents:

Apmetrix Android SDK Integration

Apmetrix Android SDK Functions

Integrating the Apmetrix SDK with Android (Java)

The following simple steps explain how to implement our SDK into your game or other mobile application.

STEP 1 - Add the SDK to project build path in Eclipse.

PackageExplorer.png

 - If the folder doesn’t already exist, create a new one called ‘libs’ in your project folder.

- Copy the

Apmetrix.jar

file to this folder.

- Refresh your project by “right clicking” the project name and selecting Refresh.  The ‘libs’ folder will now be visible in Eclipse with the Apmetrix.jar file inside.

- Check the project properties, Java Build PathApmetrix.jar should appear in the Libraries tab under Android Dependencies.  Alternately Apmetrix.jar should be visible in the Android Dependencies directory of your project folder.

BuildPath.png

 

STEP 2 - Add the following permissions to the project’s manifest file (AndroidManifest.xml).

 Manifest.png

Next, you need to connect with the Apmetrix application server:

"android.permission.INTERNET" />

Next, determine whether the device is online or offline:

"android.permission.ACCESS_NETWORK_STATE" />

Finally, determine global position (geo-location) information:

"android.permission.ACCESS_FINE_LOCATION" />

To enable Android Ad Id this meta block goes inside the <application> block:

<meta-data android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />

The Apmetrix SDK now depends on Google Play Services for collecting the Android Ad Id & GCM. The library is built against Google Play Services, but does not package it for applications. To have Apmetrix collect the Android Ad Id for attribution your app needs to include Google Play Services as a dependency. Set up instructions can be found here.

  

STEP 3 – Interface with the Apmetrix SDK:

Add the following import path to the activity(s) you are calling the SDK from:

Declaration:

import com.apmetrix.sdk.Apmetrix; 

THAT'S IT!!!  You're now collecting all of the key device and session data.  At this point you have successfully completed the integration of the SDK.  You can now set up and call the various functions you need to the Apmetrix analytics platform.


SDK FUNCTIONS

1. INITIALIZE SESSION - Initialize (i.e. start an app session) using either of the following functions:

To start an app session using default permissions use:

Function: Apmetrix.init(Context context, int appDataset, String appVersion, String appUnifier)

To start an app session using one or more of the pre-defined permissions use:

Function: Apmetrix.init(Context context, int appDataset, String appVersion, String appUnifier, int permissions)

 where:

context

A reference to the application context.  Note: it is best to call init() from your application class' onCreate() method because the application context will persist as long as your application is alive (unlike an activity's context that could be destroyed as many times as the activity is destroyed - changing screen orientations, backbutton, etc.).  Use the Application Class getApplicationContext() method to get this value.

appDataset

Identifier for the dataset used for the app data. Note: The dataset ID is sent to you when a new account has been registered or a new game has been added to your company. You will need to pass in this ID before any data can be collected.

appVersion

is a string that identifies the version of the application.

appUnifier

String which when combined with the appDataset identifies a unique app.

permissions

Optional parameter that when used defines the permissions/restrictions on the application.  This parameter is an "int" value where multiple values can be defined by "OR'ing" the values together.

 and where the optional values for permissions are:

Apmetrix.NO_GEO_LOOKUP 

Prevents the device from accessing longitude/latitude information.  In order to follow the same convention Apple uses for mobile devices this is the default permission/restriction unless otherwise specified and what is used should the init() method without a permissions parameter be called.

Apmetrix.NO_IP_LOOKUP

Prevents the device from determining its IP Address and also prevents the server from looking up information based on a user's IP address. 

Apmetrix.NO_UDID

Prevents the Universal Device ID from defining the user.  If set the user ID is defined instead by a timestamp and random number.

Apmetrix.USE_GEO_LOOKUP 

Allows the device to access longitude/latitude information.  In order to follow the same convention Apple uses for mobile devices this permission must be specifically set.  It therefore might be beneficial for the application to query the user when the application first starts to determine whether they agree to having their geo-location accessed (similar to the prompt users are given when first running an application on an Apple mobile device).

Apmetrix.ALLOW_IDFA

Allows the device to lookup the identification for advertising and report it to the server.  By default this activity is not allowed unless this permission is set.

Apmetrix.ALLOW_URL_LOGGING

Used for debugging.  When this permission is set, useful debugging information will be logged to the console such as the url sent to the server and whether data is being buffered in the database or not. 

Apmetrix.CHILD_SAFE

A shortcut permission option for the highest COPPA compliance.  It's equal to Apmetrix.NO_GEO_LOOKUP | Apmetrix.NO_IP_LOOKUP | Apmetrix.NO_UDID.  See the document "Children's Online Privacy Protection Act" for further information.

Note: The appDataset and appUnifier can be found in the dashboard under Tasks->Administration->Accounts, expanding Datasets,and selecting your Dataset.

This method returns an “int” value to indicate the resulting status of the function call and will equal one of the following:

 (0) Apmetrix.SUCCESS 

Successful operation.

 (101)   Apmetrix.WARNING_IGNORED_SESSION_ALREADY_OPEN 

Function call was ignored because a session was already open.

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS 

Operation could not be completed because the parameters passed were incorrect.

 (202) Apmetrix.ERROR_APP_CONFIG 

Operation could not be completed because there was a device configuration issue (i.e. missing manifest permissions, device parameters disabled, etc.).  Check the log files to see the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

Note:  If you plan to use Push Notifications in you application then you need to reference the section Writing the Android Application in the document "Creating a Google API Project + Obtaining an ID and Key + Setting Up Push Notifications" to see how the init() method is overloaded to support push notifications.

2. RESTARTING SESSION - To restart a session use the following function:

Function: Apmetrix.restartSession()

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

 (0) Apmetrix.SUCCESS 

Successful operation.

 (102) Apmetrix.WARNING_IGNORED_SESSION_NOT_INITIALIZED

Function call was ignored because a session had not yet been initialized with a call to Apmetrix.init().

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS 

Operation could not be completed because the parameters passed were incorrect.

 (202) Apmetrix.ERROR_APP_CONFIG 

Operation could not be completed because there was a device configuration issue (i.e. missing manifest permissions, device parameters disabled, etc.).  Check the log files to see the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

3. ADDING CUSTOM EVENTS - To add custom events/tags to your game or app use the following function:

Function: Apmetrix.logEvent(int table, String... dimensions)

where:

table

Predefined value for the type of event. Allowable values are:

  • otherTable - Any event that cannot be put into any of the other predefined tables
  • actionsTable - Any event that is triggered by the user
  • appTable - Any event that is triggered by the app
  • ftueTable - Any event that is a first time user event
  • engageTable - Any event that is related to engagement

dimensions

Variable length comma delimited list of custom event dimensions.

Note: The platform has the ability to take in up to 25 string dimensions (maximum) and 4 metric dimensions (maximum).

Adding custom events to your game or app is hugely beneficial and highly encouraged as it allows you to track many types of events and actions that users and applications generate.  Our platform allows you to pass in an unlimited number of these events and track them in many different ways.  While this functionality is extremely powerful, it can also be very unwieldy if some best practices are not thought of or contemplated in advance.  While you can of course create as many dimensions as you like (up to 24 in fact), we have suggested a logical way using 4 dimensions which may make it easier to create and and report on your custom data.

We have predefined several datasets which should cover most of custom events which you would want to track:

User Events:                  

This can be any event created by a user in your game or app. 

Application Events:     

These are events generated by your game or app and are events not associated with user actions.

Un-Grouped Events:   

These are any custom events which are not covered under with the User or Application events.

As a game or app can have many such custom events, it is important to logically categorize your local application variables as you would logically think such an event should be tracked.  A suggested structure (at least for the first four dimensions) would be as follows;

  • Verb – What event is occurring such as “crashed”, “invited”, “fired”, “damaged” etc.
  • Object – What action is occurring on what object such as “car”, “friend”, “house” etc.
  • Location – Where did such an event occur?  It is useful to think of this within the context of your game or app as each is different based on context.  For example; for an adventure game you may want to list the map or level where the event occurred.  For a racing game, perhaps the track, or for a puzzle game, the name of the puzzle or level.  Think in terms of relevant location data you’d need to know.
  • Value – This is additional information in the form of a string you may wish to pass in depending on the specific event you are tracking. For example; you may want to pass in the time for the car crashed, determine whether a condition was True or False, etc.
  • Numerical Value - This is additional information you may wish to pass in depending on whether or not you need to pass in a number (i.e. if you want to track currency or economy flows such as "Primary Currency at Session Start", Primary Currency Earned", "Primary Currency Spent", "Primary Currency at Session End" ).

Important Notes:

Since the system defaults to treating incoming data as strings, you will need to include the “#” symbol in front of your metric data so the system recognizes it as a numerical value.

Also note that since these are literal examples you will need to replace the parameter with the actual local game variable you wish to pass in to the platform so as to appropriately reflect your own data structure.


Custom Event Code Examples:

Following are some examples that demonstrate use of the logEvent() function using the above suggested ordering or dimensions.

Apmetrix.logEvent(Apmetrix.actionsTable, “Car Status”, “Type of Race”, “Track Name”, “Time and Date”);
Apmetrix.logEvent(Apmetrix.actionsTable, “Character Action”, “Spell Type”, 
“Level”, “Power”);
Apmetrix.logEvent(Apmetrix.actionsTable, “Offerwall Popup”, “Offer Type”, 
“Where Offer Selected”, "Purchased");
Apmetrix.logEvent(Apmetrix.appTable, “Logon”, "", “Facebook”, "");
Apmetrix.logEvent(Apmetrix.otherTable, “Start Session”, 
“Primary Virtual Currency”, "", “#Currency Amount”);
Note: These are for example only and you are not limited to using this or any structure in sending custom events.  Simply replace the custom tags listed with your own game or app variables which occurred at the time of the event.  If there is no data in a particular field, make sure to put an empty string ("") in the function call.
 

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

 (0) Apmetrix.SUCCESS

Successful operation.

 (103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to log event data to.

 (104) Apmetrix.WARNING_IGNORED_SOME_EVENT_PARAMETERS

Function call was ignored because there was too many input parameters.

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

4. ADDING “ONE-TIME” CUSTOM EVENTS:  To add a custom event/tag to your game or app that is not repeated but occurs only once use the following function:

Function: Apmetrix.logOneTimeEvent(int table, String oneTimeTag, String... dimensions)

where:

table

Predefined value for the type of event. Allowable values are:

  • otherTable - Any event that cannot be put into any of the other predefined tables
  • actionsTable - Any event that is triggered by the user
  • appTable - Any event that is triggered by the app
  • ftueTable - Any event that is a first time user event
  • engageTable - Any event that is related to engagement

oneTimeTag

Name identifying this one-time event

dimensions

Variable length comma delimited list of custom event dimensions.

 

Note:  See the documentation for the Apmetrix.logEvent() function for:

  1. the predefined values used for the table parameter,
  2. code examples of how the dimensions parameter may be used and,
  3. values the function can return to indicate the resulting status of the function call.

5. SEND URL REQUEST - To send a custom URL request use the following function:

Function: Apmetrix.sendRequest(Map<String, String> requestData);

where:

requestData

Dictionary of url key value pairs.

This sendRequest() method returns an “Int” value to indicate the resulting status of the function call and will equal one of the following:

(0) Apmetrix.SUCCESS

Successful operation.

(102) Apmetrix.WARNING_IGNORED_SESSION_NOT_INITIALIZED

Function call was ignored because a session had not been initialized with a call to initWithDataset().

(103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to log event data to.

(104) Apmetrix.WARNING_IGNORED_SOME_EVENT_PARAMETERS

Function call was ignored because there were too many input parameters.

(201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the original call to initWithDataset() had an invalid dataset or unifier.

(203) Apmetrix.ERROR_EVENT_DROPPED

Operation could not be completed due to a server error causing internal buffers to reach their maximum capacity. Check the log files for information on the specific error.

(204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error. Check the log files for information on the specific error.

6. TRACKING USER INTERACTION – To log coordinates of user events on specific screens use the following function:

Function: Apmetrix.ApTrak(String event, String location, String... coordinates);

event

identifies the event being logged

location

identifies the location or screen the event occurred on

coordinates

a list of coordinates for the event ordered as X, Y, [Z] and [W] (where X and Y are required and Z and W are optional)

 Tracking User Interaction code example where optional Z coordinate is used (but not W coordinate):

Apmetrix.ApTrak(“died”, “screen 2”, “25.5”, 480.75”, “14.25”);

 This method returns an "int" value to indicate the status of the function call and will equal one of the following:

 

 (0) Apmetrix.SUCCESS

Successful operation.

 (103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to log event data to.

 (104) Apmetrix.WARNING_IGNORED_SOME_EVENT_PARAMETERS

Function call was ignored because there were too many input parameters.

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

7. IN APPLICATION PURCHASES - To log a purchase made with real currency (as opposed to virtual currency). Depending on how you want the converted cost to be generated:

Use the following function when you want the converted cost to be generated based on:

  • the users IP address (to determine local currency) and
  • your country's currency (the country you specified when you created an account with Apmetrix)
Function: Apmetrix.inApPurchase(int quantity, String item, String location, double itemCost);

Use the following function when you want the converted cost to be generated based on local and converted currencies you provide:

Function: Apmetrix.inApPurchase(int quantity, String item, String location, double itemCost, String localCurrency, String convertedCurrency);

where

 quantity

identifies the amount of items purchased

 item

identifies the item(s) that were purchased

 location

identifies where within the application the user purchased the item(s)

 itemCost

identifies the cost that the user purchased the item(s) for

 localCurrency

currency the user purchased the item(s) with.  It is suggested to use the pre-defined values for local currency to avoid errors when the exchange rate is generated.  Refer to the document, "Using the In-App Purchase Function to Track Individual User Revenues" for information on these pre-defined values and further information.

 convertedCurrency

currency that the local cost will be converted to.  It is suggested to use the pre-defined values for converted currency to avoid errors when the exchange rate is generated.  Refer to the document, "Using the In-App Purchase Function to Track Individual User Revenues" for information on these pre-defined values and further information.

In Application Purchase Code Examples:

Following are some examples that demonstrate use of the inApPurchase() function using both function call options.

Apmetrix.inApPurchase(25, "gems", "Main Screen", 2.25);
Apmetrix.inApPurchase(25, "gems", "Main Screen, 2.25, Apmetrix.EUR, Apmetrix.USA);

 

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

 

 (0) Apmetrix.SUCCESS

Successful operation.

 (103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to log event data to.

 (104) Apmetrix.WARNING_IGNORED_SOME_EVENT_PARAMETERS

Function call was ignored because there was too many input parameters.

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

 

8. VIRTUAL CURRENCY TRANSACTION TRACKING - To track the flow of virtual in-game currency use the following function:

Function: Apmetrix.virtualCurrency(String transaction, String location, int... currencyAmounts);

where

 transaction

identifies the transaction that was made ("Bought", "Sold", "Traded", etc.)

 location

identifies where within the application the transaction took place

 currencyAmounts

a list of currency amounts for the item(s).  Up to 3 different denominations can be specified but denominations must be kept in the same order each time this function is called.  For example, if this function is called once with a primary currency amount and secondary currency amount then each call to this function must have at least a primary currency amount even if it is 0.

Virtual Currency Transaction Code Examples:

The following is an example that demonstrates use of the virtualCurrency() function when 12 units of a primary currency, 0 units of secondary currency and 24 units of a tertiary currency were earned:

Apmetrix.virtualCurrency("Earned", "Main Screen", 12, 0, 24);

The following is an example that demonstrates use of the virtualCurrency() function when 24 units of a primary currency and 12 units of a secondary currency were spent:

Apmetrix.virtualCurrency("Spent", "Main Screen", -24, -12);

This method returns an "int" value to indicate the status of the function call and will equal one of the following: 

 (0) Apmetrix.SUCCESS

Successful operation.

 (103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to log event data to.

 (104) Apmetrix.WARNING_IGNORED_SOME_EVENT_PARAMETERS

Function call was ignored because there was too many input parameters.

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

 

9. VIRTUAL ITEM TRANSACTION TRACKING - To track the flow of virtual in-game items and virtual in-game currency use the following function:

Function: Apmetrix.virtualItem(String transaction, int quantity, String type, String location, int... currencyAmounts);

where

 transaction

identifies the transaction that was made ("Bought", "Sold", "Traded", etc.)

 quantity

identifies the amount of items involved in the transaction

 type

identifies the type of item(s) involved in the transaction

 location

identifies where within the application the transaction took place

 currencyAmounts

a list of currency amounts for the item(s).  Up to 3 different denominations can be specified but denominations must be kept in the same order each time this function is called.  For example, if this function is called once with a primary currency amount and secondary currency amount then each call to this function must have at least a primary currency amount even if it is 0.

Virtual Item Transaction Code Examples:

The following is an example that demonstrates use of the virtualItem() function when 24 units of a primary currency and 48 units of a secondary currency were spent to buy 25 gems:

Apmetrix.virtualItem("Bought", 25, "gems", "Main Screen", 24, 48);

The following is an example that demonstrates use of the virtualItem() function when 0 units of a primary currency, 12 units of a secondary currency and 24 units of a tertiary currency were received when selling 25 gems:

Apmetrix.virtualItem("Sold", 25, "gems", "Main Screen", 0, 12, 24);

This method returns an "int" value to indicate the status of the function call and will equal one of the following: 

 (0) Apmetrix.SUCCESS

Successful operation.

 (103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to log event data to.

 (104) Apmetrix.WARNING_IGNORED_SOME_EVENT_PARAMETERS

Function call was ignored because there was too many input parameters.

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

 

10. OFFER TRACKING - To track offers presented to the user, accepted by the user or declined by the user use the following function:

Function: Apmetrix.offer(int transaction, String offer, String location);

where

 transaction

identifies the transaction that was made and has the following pre-defined values:

 PRESENTED - to denote an offer presented to the user

 ACCEPTED - to denote an offer accepted by the user

 DECLINED - to denote an offer declined by the user

 offer

String identifying the actual offer presented, accepted or declined

 location

identifies where within the application the offer was presented, accepted or declined

Offer Transaction Code Examples:

The following is an example that demonstrates use of the offer() function where "Weekend sale" was presented to the user on the main screen:

Apmetrix.offer(Apmetrix.PRESENTED, "Weekend sale", "Main Screen");

The following is an example that demonstrates use of the offer() function where "30% off gems" was accepted by the user on the pay to rush screen:

Apmetrix.offer(Apmetrix.ACCEPTED, "30% off gems", "Pay to Rush Screen");

The following is an example that demonstrates use of the offer() function where "1 for 4 stock split" was declined by the user on the intro screen: 

Apmetrix.offer(Apmetrix.DECLINED, "1 for 4 stock split", "Intro Screen");

This method returns an "int" value to indicate the status of the function call and will equal one of the following: 

 (0) Apmetrix.SUCCESS

Successful operation.

 (103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to log event data to.

 (104) Apmetrix.WARNING_IGNORED_SOME_EVENT_PARAMETERS

Function call was ignored because there was too many input parameters.

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

11. START EVENT TIMER - To start a timer for events that occur on this device you would like to know the duration of use the following function:

Function: Apmetrix.startEventTimer(String event);

where

event

Identifies the event the timer is being started for.

This startEventTimer() method returns an “Int” value to indicate the resulting status of the function call and will equal one of the following:

 

(0) Apmetrix.SUCCESS

Successful operation. 

(102) Apmetrix.WARNING_IGNORED_SESSION_NOT_INITIALIZED

Function call was ignored because a session had not been initialized with a call to initWithDataset().

(103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because a session was not open to log event data.

(201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the original call to initWithDataset() had an invalid dataset or unifier.

(203) Apmetrix.ERROR_EVENT_DROPPED

Operation could not be completed due to a server error causing internal buffers to reach their maximum capacity. Check the log files for information on the specific error.

(204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error. Check the log files for information on the specific error.

12. STOP EVENT TIMER - To stop an event timer that has previously been started and log the event's duration use the following function:

Function: Apmetrix.stopEventTimer(String event);

where

event

Identifies the event the timer is being stopped for. This value must match the parameter used when the timer was started otherwise the function will be ignored.

This stopEventTimer() method returns an “Int” value to indicate the resulting status of the function call and will equal one of the following:

 

(0) Apmetrix.SUCCESS

Successful operation.

(102) Apmetrix.WARNING_IGNORED_SESSION_NOT_INITIALIZED

Function call was ignored because a session had not been initialized with a call to initWithDataset().

(103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because a session was not open to log event data.

(201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the original call to initWithDataset() had an invalid dataset or unifier.

(203) Apmetrix.ERROR_EVENT_DROPPED

Operation could not be completed due to a server error causing internal buffers to reach their maximum capacity. Check the log files for information on the specific error.

(204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error. Check the log files for information on the specific error.

13. PAUSE ALL EVENT TIMERS - To pause all event timers started for this device when your application transitions to background use the following function:

Function: Apmetrix.appDidEnterBackground(Activity activity);

where

activty

A reference to the application activity this function is called from.  The application activity is used to 

Notes:  

  1. It is suggested this function be called from your activity's onStop() methods. Failure to call this method, or calling it from the wrong activity method may result in incorrect timer durations being logged for your events.
  2. If it is determined this function was called solely as a result of a configuration change (i.e. a change in orientation from landscape to portrait or vice versa) then this function does nothing.  

14. RESUME ALL EVENT TIMERS – To resume all event timers started for this device that were paused when your application was in background use the following function:

Function: Apmetrix.appWillEnterForeground();

Notes:

  1. It is suggested this function be called from your activity's onStart() methods. Failure to call this method, or calling it from the wrong activity method may result in incorrect timer durations being logged for your events.
  2. If the function to pause all event timers was called as a result of a configuration change then a call to this function does nothing as well.

15. START LEVEL - Call this function when a player starts a new level. This is used to record how long it took the player to reach the each next level.

Function: Apmetrix.startLevel(String level);

 

Example:

Called when the game is launched for the very first time.

Apmetrix.startLevel ("1");

 

Called when the player levels up.

Apmetrix.startLevel ("2");

 

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

 (0) Apmetrix.SUCCESS

Successful operation.

 (103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to end (or close).

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error. 

 

16. SET LOCATION - To track a customer's movement through the application use the following function:

Function: Apmetrix.setLocation(String location);

where

 location

 identifies the user is currently within the game or app..

Location Tracking Code Example:

The following is an example that demonstrates use of the setLocation() function where "Screen 3" is the name of the screen the user is now on:

Apmetrix.setLocation("Screen 3");

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

 (0) Apmetrix.SUCCESS

Successful operation.

 (103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to log event data to.

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error.  Check the log files for information on the specific error.

17. CUSTOMER TRACKING - To track a customer ID so it can be correlated with the rest of the data being tracked on this mobile device for this user use the following function:

Note:  This method is useful for applications where the user can be identified via a logon ID or user id, thus allowing the rest of the data tracked to be correlated on a per user basis.  To log a customer ID call:

Function: Apmetrix.setCustomerId(String customerId);

where

 customerId

 identifies the user playing the game or logged on to the app.

Customer Tracking Code Example:

The following is an example that demonstrates use of the setCustomerId() function where "Number 1 Fan" is the ID the customer is identified by:

Apmetrix.setCustomerId("Number 1 Fan");

This method returns an "int" value to indicate the status of the function call and will equal one of the following: 

 (0) Apmetrix.SUCCESS

Successful operation.

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Returned if the call to setCustomerId() had a null value for the customerId.

18. SET APTRAK BUNDLE COUNT - Call this function to indicate how many ApTrak calls you want to bundle before sending them to the Apmetrix Server. If you set the count to 1 then there will be no bundling.

Function: Apmetrix.setBundleCount(int count);

 

Example:

This example bundles 50 ApTrak calls together then sends the data to the Apmetrix server

Apmetrix.setBundleCount(50)

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

 (0) Apmetrix.SUCCESS

Successful operation.

 (103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to end (or close).

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error. 

 

19. SET UPLOAD INTERVAL - Call this function to indicate how many minutes the SDK should wait before sending data to the Apmetrix Server.

Function: Apmetrix.setUploadInterval(int minutes);

 

Example:

This example tells the SDK to wait 5 minutes before sending data.

Apmetrix.setUploadInterval(5);

 

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

 (0) Apmetrix.SUCCESS

Successful operation.

 (103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to end (or close).

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error. 

 

 

20. END SESSION - To end a session, use the following function:

Function: Apmetrix.endSession()

This method returns an "int" value to indicate the status of the function call and will equal one of the following:

 (0) Apmetrix.SUCCESS

Successful operation.

 (103) Apmetrix.WARNING_IGNORED_SESSION_NOT_OPEN

Function call was ignored because there was not an open session to end (or close).

 (201) Apmetrix.ERROR_INVALID_ARGUMENTS

Operation could not be completed because the parameters passed were incorrect.  Check the log files for information on the specific error.

 (203) Apmetrix.ERROR_EVENT_DROPPED 

Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.

 (204) Apmetrix.ERROR_FAILED

Operation could not be completed because of some other error. 

 

 

 

 Technical Release Notes:

** Function Updates **

  • We have added a function called Apmetrix.notificationHandler() that returns your Notification data as a Map<String, String>. At minimum this function will return the Notification message via key message.
  • Added better GCM related error handling. Use tag:ApmetrixGCM to filter to any GCM messages. 
  • Added better error handling for SDK in general. Use tag:ApmetrixSDK- to filer URL messages (*If ALLOW_URL_LOGGING is set). Use tag:Apmetrix for the main Apmetrix API filter


** Linking Updates **

  • Now build against the Google Play Services library
  • Need to include the google-play-services_lib inside your Plugins/Android folder. This can be found at <AndroidSDK_Location\sdk\extras\google\google_play_services\libproject>
  • Need to include a meta-data block inside your manifest file
  • <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />
  • Now link with android-support-v4.jar
  • If another plugin developer includes this jar could cause build errors but we only include the files we need for Push Notifications. Please be advised!

** GCM Updates **

  • New setup for initializing Android Push Alert Notifications
  • Strings.xml file has been removed
  • Can setup your own custom LAUNCH & CLOSE button names via Unity function:
  • pushNotificationAlertConfig (String launchName, String closeName) in Apmetrix.java file
  • Res folder Changes:
  • The Strings.XML file has been removed
  • Use the pushNotificationAlertConfig (String launchName, String closeName) to change names
  • To change the icon for GCM you will need to overwrite the ic_dialog_gcm.png & the ic_dialog_gcm.png in the res/drawable folders but you must NOT change the name. 


** Special Notes **

  • The bar (|) is a reserved symbol and should not be used in your push notifications
  • The key apxK is a reserved key notation and should not be used in your key value pairs
  • Example
  • Setting the App Name 
  • Native:
  • Must set app name in <application> via android:label="Apmetrix Test App" 


** Android Ad Id **

  • Now collect the Android Ad Id:
  • Set this collection by setting the ALLOW_IDFA permission

 

Have more questions? Submit a request