Follow

Integrating the Apmetrix Titanium SDK

This article will cover the steps needed to integrate the Apmetrix Titanium SDK which supports IOS and Android deployment.

Table of Contents

  1. Downloading the Titanium SDK
  2. Integrating the Apmetrix IOS Module
  3. Integrating the Apmetrix Android Module
  4. Understanding the Apmetrix Functions
  5. Method return values

1. Downloading the Titanium SDK

You can download the Apmetrix Titanium SDK from http://support.apmetrix.com/entries/23626702-Download-Apmetrix-SDK-s

Make sure you have your Titanium Studio open with the project you are wanting to integrate the sdk into as we will reference it throughout parts of this article.

In your project you will need to create a folder called modules if you do not already have one as shown in the picture below.

Screen_Shot_2014-02-05_at_1.09.54_PM.png

 

2. Integrating the Apmetrix IOS Module

After downloading the Apmetrix Titanium SDK unzip the sdk which contains two folders, iPhone and Android. First we are going to integrate the IOS Module.

First you will want to drag the iPhone folder into the modules folder. Your modules folder should look like the following

Screen_Shot_2014-02-05_at_1.10.30_PM.png

That is it.

3. Integrating the Apmetrix Android Module

Going back into the folder that we originally started on we will now integrate the Android module.

You will want to drag the Android folder into the modules folder. Your modules folder should look like the following

Screen_Shot_2014-02-05_at_1.10.30_PM.png

Next open up your tiapp.xml file and click on the tiapp.xml tab in the bottom left. Scroll down till you see

<android xmlns:android="http://schemas.android.com/apk/res/android"/>

You will need to replace this with the following:

    <android xmlns:android="http://schemas.android.com/apk/res/android">

        <manifest>

            <uses-permission android:name="android.permission.INTERNET"/>

            <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

            <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

        </manifest>

    </android>

These permissions are required for the Apmetrix SDK to function correctly.

Finally we need to include the modules in the app. To do so click on the Overview tab on the tiapp.xml file. This will bring us to the graphical view of the xml file. In the Modules area on the right click on the + (plus) sign which will open up a window as shown below.

Screen_Shot_2014-02-05_at_1.16.51_PM.png

From here you will want to select the com.apmetrix module as shown below

Screen_Shot_2014-02-05_at_1.17.36_PM.png

Your module window should now look like the following.

Screen_Shot_2014-02-05_at_1.15.38_PM.png

Now you are ready to start using the Apmetrix Titanium SDK. Next we will be going over the functions provided by Apmetrix.

4. Understanding the Apmetrix Functions

*NOTE: To access the Apmetrix functions you will need to add the following in each script that you are planning to use Apmetrix in.

 

var Apmetrix = require('com.apmetrix');

 

Initialize Session

Call the following method to initialize a session using default permissions:

Apmetrix.Apmetrix_init(int appDataset, string appVersion, string appUnifier);

INITIALIZE EXAMPLE WITHOUT PERMISSIONS:

Apmetrix.Apmetrix_init(12345, "1.0.0", "1234567890ABCDEFG");

 

Call the following method to initialize a session using non-default permissions:

Apmetrix.Apmetrix_init(int appDataset, String appVersion, String appUnifier, int permissions);

INITIALIZE EXAMPLE WITH PERMISSIONS:

Apmetrix.Apmetrix_init(12345, "1.0.0", "1234567890ABCDEFG", Apmetrix.CHILD_SAFE);

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

Note 2: If needing to initialize the session with non-default permissions you can select from any combination of the following options. If more than one option is desired the options can be or'd together using the | character:

(1) Apmetrix.NO_GEO_LOOKUP

The device GPS location is NOT sent to the server (Deprecated)

(2) Apmetrix.NO_IP_LOOKUP

The device external IP address is NOT sent to the server

(4) Apmetrix.NO_UDID

The device's unique identifier is NOT sent to the server

(8) Apmetrix.USE_GEO_LOOKUP

The device will track GPS location. By default the sdk will not track GPS.

(7) Apmetrix.CHILD_SAFE

Combination of the NO_GEO_LOOKUP, NO_IP_LOOKUP and NO_UDID permissions

(16) Apmetrix.IN_APP_POPUP

Tells the device that you want an In App Popup for Push Notifications.

 

(32)   Apmetrix.ALLOW_IDFA

Allows the device to lookup and send to the server the devices "identifier for advertisers".  By default the IDFA is NOT looked up and sent to the server.  The "identifier for advertisers" is needed for ad tracking so advertisers can know when a user has clicked on their advertisement.

 

Adding Custom Events

Call the following method to log custom events.

Apmetrix.Apmetrix_logEvent(int table, string[] dimensions);

table

Predefined value for the type

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.

Integer values for the table parameter are as follows:

(1)       Apmetrix.UN_GROUPED_TABLE

The dimension data is ungrouped

(2)       Apmetrix.USERS_TABLE

The dimension data pertains to the user

(3)       ApmetrixStatic.APPS_TABLE

The dimension data pertains to the application

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.

IMPORTANT NOTE:

This function has different parameters in Android than it does in IOS. Please review the example accordingly.

To differentiate the function calls correctly use the following code.

var osname = Ti.Platform.osname;

// Booleans identifying the platforms are handy too

var isAndroid = (osname=='android') ? true : false;

if(isAndroid) {

     Apmetrix.Apmetrix_logEvent(Apmetrix.APPS_TABLE, ["verb", "", "location", "#100", "#200", "#300"]);

}else{ //Otherwise use the IOS code

     Apmetrix.Apmetrix_logEvent(Apmetrix.APPS_TABLE, "verb", "", "location", "#100", "#200", "#300");

}

Below is a break down of how the dimensions and metrics are split up:

Dimension 1 - verb

Dimension 2 - (In this case since dimension 2 is an empty string nothing is passed for dimension 2)

Dimension 3 - location

Metric 1 - 1 (Metric 1 does not need to be passed in by the developer. It always has a value of one since it specifies how many times this event was called)

Metric 2 - 100

Metric 3 - 200

Metric 4 - 200

 

ApTrak

Call the following method  to track user interaction, logging the coordinates for a specified event at a specified location or screen: 

Apmetrix.Apmetrix_ApTrak(event, location, [coordinates]);

 

IMPORTANT NOTE:

This function has different parameters in Android than it does in IOS. Please review the example accordingly.

To differentiate the function calls correctly use the following code.

var osname = Ti.Platform.osname;

// Booleans identifying the platforms are handy too

var isAndroid = (osname=='android') ? true : false;

if(isAndroid) {

     Apmetrix.Apmetrix_ApTrak("touch", "screen1", [touchPos.x, touchPos.y]);

}else{ //Otherwise use the IOS code

     Apmetrix.Apmetrix_ApTrak("touch", "screen1", touchPos.x, touchPos.y);

}

 

 Event coordinates should be input in the following order:

X (required), Y (required), Z (optional) and W (optional)

 

IN APPLICATION PURCHASES

 To log a purchase made with real currency (as opposed to virtual currency):

 You will want to reference the In-App Purchase document for more details on In App Purchases.

 This function ties to the In-App Purchases Table. 

 Function Call - 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) :
Apmetrix.Apmetrix_inApPurchase(quantity, item, location, itemCost); 

or ...

Function Call - when you want the converted cost to be generated based on local and converted currencies you provide:

Apmetrix.Apmetrix_inApPurchase(quantity, item, location, itemCost, localCurrency);

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 items

 itemCost

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

 localCurrency

currency that the user purchased the items with.  It is suggested to use the pre-defined values for local currency to avoid errors in exchange rate generation.  These pre-defined values are shown in In-App Purchase document

 

In Application Purchase Code Examples:

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

If you do not know the local currency or what currency you want to convert to use this example. We will do the conversion server side using data from your App Setup on the Apmetrix Dashboard.

Apmetrix.Apmetrix_inApPurchase(1, "100 Gem Package", "Main Screen", 2.25);

 If you know the local currency  go ahead and use this example

Apmetrix.Apmetrix_inApPurchase(1, "100 Gem Package", "Main Screen, 2.25, EUR);

 

Virtual Item Transaction Tracking

Call the following method to log virtual item transactions.

Apmetrix_t.virtualItem(transaction, qty, itemType, location, primaryCurrency);

Apmetrix_t.virtualItem(transaction, qty, itemType, location, primaryCurrency, secondaryCurrency);

Apmetrix_t.virtualItem(transaction, qty, itemType, location, primaryCurrency, secondaryCurrency, tertiaryCurrency);

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.

Use this function when you want to track the flow of in-game items & in-game currency. This function ties to two tables (Virtual Currency & Virtual Items) on the Apmetrix Dashboard. 

 

IMPORTANT NOTE:

This function has different parameters in Android than it does in IOS. Please review the example accordingly.

To differentiate the function calls correctly use the following code.

var osname = Ti.Platform.osname;

// Booleans identifying the platforms are handy too

var isAndroid = (osname=='android') ? true : false;

if(isAndroid) {    

//This example shows 1 Wand of Hate was sold at the Evil Shop for 15 primaryCurrency, 20 secondaryCurrency and 5 tertiaryCurrency

     Apmetrix.Apmetrix_virtualItem("Sold", 1, "Wand of Hate", "Evil Shop", [15, 20, 5]);

//This example shows 1 Wand of Luck was bought at the Evil Shop for 15 primaryCurrency, 20 secondaryCurrency

    Apmetrix.Apmetrix_virtualItem("Bought", 1, "Wand of Luck", "Evil Shop", [15, 20]);

This example shows 1 Wand of Greed was pawned at the Evil Shop for 15 primaryCurrency

    Apmetrix.Apmetrix_virtualItem("Pawned", 1, "Wand of Greed", "Evil Shop", [15]);

}else{ //Otherwise use the IOS code

//This example shows 1 Wand of Hate was sold at the Evil Shop for 15 primaryCurrency, 20 secondaryCurrency and 5 tertiaryCurrency

     Apmetrix.Apmetrix_virtualItem("Sold", 1, "Wand of Hate", "Evil Shop", 15, 20, 5);

//This example shows 1 Wand of Luck was bought at the Evil Shop for 15 primaryCurrency, 20 secondaryCurrency

    Apmetrix.Apmetrix_virtualItem("Bought", 1, "Wand of Luck", "Evil Shop", 15, 20);

This example shows 1 Wand of Greed was pawned at the Evil Shop for 15 primaryCurrency

    Apmetrix.Apmetrix_virtualItem("Pawned", 1, "Wand of Greed", "Evil Shop", 15);

}

 

Offer Tracking

 Call the following method to log offers that are presented/accepted/declined.

Apmetrix.Apmetrix_offer(transaction, offerType, location);

 where

 transaction

identifies the transaction that was made and has the following meanings:

 Apmetrix.PRESENTED- used to denote an offer presented to the user

 Apmetrix.ACCEPTED - used to denote an offer accepted by the user

 Apmetrix.DECLINED - used to denote an offer declined by the user

 offer

identifying the actual offer "30% off weekend sale", "10% off all Gems", etc

 location

identifies where within the application the offer was presented, accepted or declined. "Main Menu", "Pay To Rush", "Cash Shop", etc

 This function ties to the Offers Table on the Apmetrix Dashboard.

 

Examples:

Use this example when you want to track an offer that was Presented to the user

Apmetrix.Apmetrix_offer(Apmetrix.PRESENTED, "Weekend Sale 20% Offer", "main menu");

 

Use this example when you want to track an offer that was Accepted by the user 

Apmetrix.Apmetrix_offer(Apmetrix.ACCEPTED, "Weekend Sale 20% Offer", "payToRush");

 

Use this example when you want to track an offer that was Declined by the user 

Apmetrix.Apmetrix_offer(Apmetrix.DECLINED, "Weekend Sale 20% Offer", "cash shop");

 

Start Timer

Call the following method to start a new timer:

Apmetrix.Apmetrix_startTimer(timerName);

Where timerName is the name of the timer. If you start a timer and that timer already exists then the system will override the existing timer.

 

Ex:

Apmetrix.Apmetrix_startTimer("Test Timer");

 The timer system will automatically pause all active timers when your app is in the background and resume all paused timers when your app is in the foreground.

 

Stop Timer

Call the following method in the to stop an existing timer:

Apmetrix.Apmetrix_stopTimer(string timerName);

Where timerName is the name of the existing timer. The system will only stop timers that exist.

 

Ex:

Apmetrix.Apmetrix_stopTimer("Test Timer");

 To better understand Timers it is recommended that you view the article on timers found here.

 

 AppDidEnterBackground

The AppDidEnterBackground functions handles all required tasks that the SDK needs to perform when your application enters the background.  For Timer functions It is important that this method be called in the proper location within your application so that the duration for the timer events you have started are accurate and only include the time the user is actively engaged with your application.

Call the following method to pause all active timers.

Apmetrix.Apmetrix_appDidEnterBackground();

 

AppWillEnterForeground

The AppWillEnterForeground functions handles all required tasks that the SDK needs to perform when your application re-enters the foreground.  For Timer functions It is important that this method be called in the proper location within your application so that the duration for the timer events you have started are accurate and only include the time the user is actively engaged with your application.

Call the following method to resume all paused timers.

Apmetrix.Apmetrix_appWillEnterForeground();

 

Restart Session

Call the following method to restart a session that had previously been initialized but closed:

Apmetrix.Apmetrix_restartSession();

 

End Session 

Call the following method to close a session that is open: 

Apmetrix.Apmetrix_endSession();

 

 

Have more questions? Submit a request