Follow

Integrating the Apmetrix iOS (Xcode) SDK

 

Table of Contents:

Apmetrix iOS SDK Integration

Apmetrix iOS SDK Functions

Apmetrix iOS SDK Integration

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

STEP 1 - Add the SDK library file

libApmetrix.a, libApmetrixNoReach.a or libApmetrixWithIDFA.a (See Note)

Note: If your application includes ad functionality then you need to use "libApmetrixWithIDFA.a".  If your application does not include ad functionality always use “libApmetrix.a” unless you are also using another iOS library that uses Reachability. If you are not sure, start by using “libApmetrix.a” and if you get the following linker errors then switch to “libApmetrixNoReach.a”

For more information on duplicate symbol related to Reachability, please refer to this article: duplicate symbol - Reachability

 

duplicate symbol _OBJC_IVAR_$_Reachability.reachabilityRef in:
duplicate symbol _OBJC_CLASS_$_Reachability in:
duplicate symbol _OBJC_METACLASS_$_Reachability in:

and header file

Apmetrix.h

to your iOS project.

iOS-Mac_1.jpg

One way to do this is to use Finder to first copy these two files into your project folder, and then select File->Add File To… to add the files. Alternatively you can use this same option to add files from another directory and select the “Copy tems into destination group’s folder (if needed)” option.

 

STEP 2 - Add the required frameworks and SQLite library to your iOS project.

 

Click on your project name in the left hand column of XCode, then select the Build Phases tab in the middle screen. Select the Link Binary With Libraries section. Click on the + sign to add libraries. You will need to add the following:

libApmetrix.a (or libApmetrixNoReach.a or libApmetrixWithIDFA.a)
libsqlite3.dylib
AdSupport.framework (only if app includes ad functionality and added libApmetrixWithIDFA.a)
SystemConfiguration.framework CoreLocation.framework UIKit.framework Foundation.framework
StoreKit.framework

Your project may already use some of these frameworks so just add the ones that are missing.

 

STEP 3 - Add the –ObjC link flag to the Other Linker Flags section

iOS-Mac_3.jpg

Select the Build Settings tab and go to the Linking section and find the Other Linker Flags subsection. Add the flag –ObjC to both Debug and Release builds.

 

STEP 4 – Interface with the Apmetrix SDK in your code

In the project App Delegate file, and anywhere else where you need to use the Apmetrix API functions, use the following import statement:

#import “Apmetrix.h”

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

All SDK functions are class methods for the Apmetrix class.

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 initWithDataset:(int)appDataset andVersion:(NSString *)appVersion andUnifier:(NSString *)appUnifier];

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

Function: [Apmetrix initWithDataset:(int)appDataset andVersion:(NSString *)appVersion andUnifier:(NSString *)appUnifier andPermissions:(int)permissions];

where:

appDataset

This number identifies 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

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 permissions can be set by "OR'ing" their values together.

and where the optional values for permissions are:

NO_GEO_LOOKUP

Prevents the device from accessing longitude/latitude information. If this permission is set the user will not be queried whether they want to allow your application to use their current location. This is the default permission/restriction should the "initWithDataset: andVersion: andUnifier:" method be called.

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.

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.

USE_GEO_LOOKUP

Allows the device to access longitude/latitude information. Even if this parameter is set the user will still be queried whether they want to allow your application to use their current location. If you want this permission set you may need to prompt the user to accept the prompt for using their current location.

CHILD_SAFE

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

ALLOW_POPUP_IN_APP

Allows the device to display pop-up alert dialogs for push notifications if the notification was received while the application is active in the foreground. Without this permission set, pop-up alert dialogs are only displayed for push notifications when the application is inactive or in the background. By default push notifications are NOT displayed when they are received while the application is active.

ALLOW_IDFA

Allows the device to lookup and send to the server the device's "identifier for advertisers".  By default the IDFA is NOT looked up and sent to the server so this flag should be set if the application is going to be displaying any advertising. The "identifier for advertisers" is needed for ad tracking so advertisers can know when a user has clicked on their advertisement.

Note: the actual lookup of the "identifier for advertisers" is done and only possible with the version of the iOS SDK that includes IDFA code (libApmetrixWithIDFA.a).

NO_IDFA

Prevents the device from looking up and sending the device's "identifier for advertisers" to the server. This flag is set by default for the version of the iOS SDK that include IDFA code (libApmetrixWithIDFA.a). The "identifier for advertisers" is needed for ad tracking so advertisers can know when a user has clicked on their advertisement.

Note: If your application does not include ad functionality it is recommended to NOT use the version of the iOS SDK that includes IDFA code (libApmetrixWithIDFA.a). Instead use libApmetrix.a. Applications that include IDFA code when they don't include ad functionality risk being rejected when they are submitted to the App Store for review.

Note: The appDataset and appUnifier can be found in the dashboard under Tasks->Administration->Accounts and expanding Datasets, then select 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.

(102) APMETRIX_WARNING_IGNORED_SESSION_NOT_INITIALIZED

Function call was ignored because a session had not yet been initialized with a call to initWithDataset:

(201) APMETRIX_ERROR_INVALID_ARGUMENTS

Returned if the original call to initWithDataset: had an invalid dataset or unifier.

(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.

2. RESTART 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 initWithDataset:

(201) APMETRIX_ERROR_INVALID_ARGUMENTS

Returned if the original call to initWithDataset: had an invalid dataset or unifier.

(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) tableType andDimensions:(NSString *)dimensions, ...];

where:

tableType

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

  • OTHER - Any event that cannot be put into any of the other predefined tables
  • ACTIONS - Any event that is triggered by the user
  • APPS - Any event that is triggered by the app
  • FTUE - Any event that is a first time user event
  • ENGAGE - Any event that is related to engagement

dimensions

Variable length comma delimited list of custom event dimensions. This list MUST be nil terminated.

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 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, thereby allowing you do apply math to the field.

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:USERS andDimensions:@"Car Status", @"Type of Race", @"Track Name", @"Time and Date", nil];
[Apmetrix logEvent:USERS andDimensions:@"Character Action", @"Spell Type", @"Level", @"Power", nil];
[Apmetrix logEvent:USERS andDimensions:@"Offerwall Popup", @"Offer Type", @"Where Offer Selected", @"Purchased", nil];
[Apmetrix logEvent:APPS andDimensions:@"Logon", @"", @"Facebook", nil];
[Apmetrix logEvent:OTHER andDimensions:@"Start Session", @"#Primary Virtual Currency", @"", @"#Currency Amount”, nil];

 

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, type an empty string “” in the function call. Terminate the list of parameters with the word nil.

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

Returned if the original call to initWithDataset: had an invalid dataset or unifier.

(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:

Function Call:

[Apmetrix logEvent:(int) tableType andTag:(NSString *)tag andDimensions:(NSString *)dimensions, ...];

where:

tableType

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

  • OTHER - Any event that cannot be put into any of the other predefined tables
  • ACTIONS - Any event that is triggered by the user
  • APPS - Any event that is triggered by the app
  • FTUE - Any event that is a first time user event
  • ENGAGE - Any event that is related to engagement

tag

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:(NSDictionary *)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:(NSString *) event andLocation:(NSString *)location andCoordinates:(NSString *)coordinates...];

where:

event

identifies the event being logged

location

identifies the location or screen the event occurred on

coordinates

a nil terminated 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”, nil];

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).

(104) APMETRIX_WARNING_IGNORED_SOME_EVENT_PARAMETERS

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

(201) APMETRIX_ERROR_INVALID_ARGUMENTS

Returned if the call to initWithDataset: had an invalid dataset or unifier.

(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.

 

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 andItem:(NSString *)item andLocation:(NSString *)location andItemCost:(float)itemCost];

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

  • the local and converted currencies you provide
Function: [Apmetrix inApPurchase:(int)quantity andItem:(NSString *)item andLocation:(NSString *)location andItemCost:(float)itemCost andLocalCurrency:(NSString *)localCurrency  andConvertedCurrency:(NSString *)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 that the user purchased the item(s) with. It is suggested to use the Apmetrix SetProductId: to get the Country Code that is obtained from the SKProduct. 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

As per Apple's guidelines listed at the following link

We required that you use the SKProduct.priceLocale to get the Country Code. Once you have the SKProduct.priceLocale value you can obtain the Country Code using the following code.

NSString *countryCode = [SKProduct.priceLocale objectForKey:NSLocaleCountryCode];
[Apmetrix inApPurchase:25 andItem:@“gems” andLocation:@“Main Screen” andItemCost:2.25 andLocalCurrency:countryCode andConvertedCurrency:CURRENCY_USD];

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).

(104) APMETRIX_WARNING_IGNORED_SOME_EVENT_PARAMETERS

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

(201) APMETRIX_ERROR_INVALID_ARGUMENTS

Returned if the call to initWithDataset: had an invalid dataset or unifier.

(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.

 

8. SET PRODUCT ID - Call this function to set internal SDK information regarding App Store Locale. Used in conjunction with In App Purchases to correctly set the player's local currency

Function: [Apmetrix setProductId:(NSString*)productId];

where:

productId

the product identifier for the In-App Purchase item(s)

This method does not return anything (i.e. void).

Example:

Called when the game is launched for the very first time

[Apmetrix setProductId:@"com.apmetrix.test.RedSword"];



 

9. VIRTUAL CURRENCY TRANSACTION TRACKING - Use this function to track the flow of virtual in-game currency. To log a virtual currency transaction use the following function:

Function: [Apmetrix virtualCurrency:(NSString *)transaction andLocation:(NSString *)location andCurrencyAmounts:(NSString *)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 nil terminated 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 with a primary currency amount and secondary currency amount then each call to this function must include 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" andLocation:@“Main Screen” andCurrencyAmounts:@"12", @"0", @"24", nil];

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" andLocation:@“Main Screen” andCurrencyAmounts:@"-24", @"-12" nil];

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).

(104) APMETRIX_WARNING_IGNORED_SOME_EVENT_PARAMETERS

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

(201) APMETRIX_ERROR_INVALID_ARGUMENTS

Returned if the call to initWithDataset: had an invalid dataset or unifier.

(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.

 

10. VIRTUAL ITEM TRANSACTION TRACKING - Use this function to track the flow of virtual in-game items and virtual in-game currency. To log a virtual item transaction use the following function:

Function: [Apmetrix virtualItem:(NSString *)transaction andQuantity:(int)quantity andType:(NSString *)type andLocation:(NSString *)location andCurrencyAmounts:(NSString *)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

itemCost

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

currencyAmounts

a nil terminated 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 with a primary currency amount and secondary currency amount then each call to this function must include 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" andQuantity:25 andType:@“gems” andLocation:@“Main Screen” andCurrencyAmounts:@"24", @"48", nil];

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 currrency were spent to buy 25 gems

[Apmetrix virtualItem:@"Bought" andQuantity:25 andType:@“gems” andLocation:@“Main Screen” andCurrencyAmounts:@"0", @"12", @"24", nil];

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).

(104) APMETRIX_WARNING_IGNORED_SOME_EVENT_PARAMETERS

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

(201) APMETRIX_ERROR_INVALID_ARGUMENTS

Returned if the call to initWithDataset: had an invalid dataset or unifier.

(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.

 

11. OFFER TRACKING - Use this function to track offers presented to the user, accepted by the user or declined by the user. To log an offer transaction use the following function:

Function: [Apmetrix offer:(NSString *)transaction andOffer:(NSString *)offer andLocation:(NSString *)location];

where:

transaction

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

1 - used to denote an offer presented to the user

2 - used to denote an offer accepted by the user

3 - used 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:1 andOffer:@"Weekend sale" andLocation:@“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:2 andOffer:@"30% off gems" andLocation:@“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:3 andOffer:@"1 for 4 stock split" andLocation:@“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 end (or close).

(104) APMETRIX_WARNING_IGNORED_SOME_EVENT_PARAMETERS

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

(201) APMETRIX_ERROR_INVALID_ARGUMENTS

Returned if the call to initWithDataset: had an invalid dataset or unifier.

(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.

12. 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 startTimerForEvent:(NSString *)event];

where

event

Identifies the event the timer is being started for.

This startTimerForEvent: 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. 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 stopTimerForEvent:(NSString *)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.

Note: Events possibly being timed as a result of paired watch application activity are kept separate (i.e. an event timer cannot be started on one device and stopped on the other). 

 

This stopTimerForEvent: 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.

14. 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];

Notes:

This function does not pause any event timers that pertain to any possible paired watch application activity.  That has to be called separately via watch messaging.

It is also suggested this function be called from your application delegate’s applicationDidEnterBackground: method. Failure to call this method, or calling it from the wrong app delegate method may result in incorrect timer durations being logged for your events.

15. 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:

This function does not resume any event timers that pertain to any possible paired watch application activity.  That has to be called separately via watch messaging.

It is also suggested this function be called from your application delegate’s applicationWillEnterForeground: method. Failure to call this method, or calling it from the wrong app delegate method may result in incorrect timer durations being logged for your events.

16. START LEVEL - To track how much time a player spent on a particular level use the following function:

Function: [Apmetrix startLevel:(NSString*)level];

Example:

Called when the game is launched for the very first time

[Apmetrix startLevel:@"Level 1"];


Called when the player levels up

[Apmetrix startLevel:@"Level 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

Returned if the original call to initWithDataset: had an invalid dataset or unifier.

(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.

 

17. SET LOCATION - Used to track a customer's movement through the application.

Function: [Apmetrix setLocation:(NSString *)location];

where:

location

identifies where 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 at:

[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

Returned if the original call to initWithDataset: had an invalid dataset or unifier.

(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.

18. CUSTOMER TRACKING - Used 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. 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 set the customer ID use the following function:

Function: [Apmetrix setCustomerId:(NSString *)customerId];

where:

customerId

identifies the user playing the game or logged onto 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 nil value for the customerId.

 

19. SET APTRAK BUNDLE COUNT - To indicate how many ApTrak calls you want to bundle before sending them to the Apmetrix Server use the following function (Note: this function is ignored if count is set to 1):

Function: [Apmetrix setApTrakBundleCount:(int)count];

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

[Apmetrix setApTrakBundleCount: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

Returned if the original call to initWithDataset: had an invalid dataset or unifier.

(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. SET UPLOAD INTERVAL - To specify how many minutes the SDK should wait before sending data to the Apmetrix Server use the following function:

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

Returned if the original call to initWithDataset: had an invalid dataset or unifier.

(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.

 

 

21. END SESSION - To end or close 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

Returned if the original call to initWithDataset: had an invalid dataset or unifier.

(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 **

  • NotificationHandler now returns an NSDictionary containing the key/value pairs that are passed down. At minimum it will contain the Push Notification Message via key "message"
  • Added a function called localNotificationHandler which tracks when users interact with device generated local notifications. These Local Notifications get stored in their own column in the Push Notification Analytics Table on the Apmetrix Platform. 

 

 

 

 

 

 

 

 

Have more questions? Submit a request