Follow

Integrating the Apmetrix Unity SDK

** Platforms Officially Supported for Non Virtual Reality Applications **

  • Editor
  • PC
  • Xbox One
  • PlayStation 4
  • Mac
  • Linux
  • Web Player
  • Android 
  • iOS

** Important Notes **

  • This document describes integration of the Apmetrix Unity SDK for non Virtual Reality applications.  For details on integrating the Apmetrix Unity SDK for Virtual Reality applications see "Integrating the Apmetrix Unity SDK (Addendum for Virtual Reality Applications)"
  • This document describes integration for Revisions 2.1.4 or greater of the Apmetrix Unity SDK.
  • Prior to Revision 2.1.4, offline event caching was ONLY supported on Android and iOS platforms.  As of Revision 2.1.4, offline event caching is supported for all platforms.
  • You must review the Setting Up For IOS steps in order to properly configure the XCODE project. 

Table of Contents

Push Notification Documentation

 

1. Getting the ApmetrixUnity SDK (for non Virtual Reality Applications)

Untitled1.png

  • Navigate to the downloaded extracted zip archive that contains the ApmetrixUnityPack(non-VR) Unity Package file, select it and click Open. 

  • This will bring up the Importing Package window.

  • Make sure all of the checkboxes are selected by pressing "All" and then press "Import". This will import the required files/folder structure into your Unity Project.
  • You should now see the following folder structure in your Assets Directory.

 

 

2. Integrating the ApmetrixUnity SDK

Adding the [Apmetrix] Prefab

  • To begin using the ApmetrixUnity plugin, find the Apmetrix prefab in the Assets->Apmetrix->Prefabs directory.

  • Drag an instance of this prefab into the hierarchy window for the scene where you want to start using analytics.

  • *Note: This object will need to persist throughout your game/app.
  • Do not re-create this object for each scene or you may experience oddities when using the SDK.

Setting the Static Apmetrix Variables

Select the Apmetrix game object in the hierarchy and in your Inspector pane you can set the Apmetrix variables necessary to initialize your analytics session.

First make sure the Apmetrix script is enabled.  This is done by default but can be double checked by making sure the check box to the left of component name, Apmetrix (Script), is checked.  When the Apmetrix script is enabled in this manner the session will be initialized automatically when the application launches and any paused timers (if there are any) will be resumed..

To set all of the necessary variables and desired permissions first select the platform this version of the application will be built for as some variables and permissions are only relevant for particular platforms.

  • The values to enter in the fields for Application Dataset and Application Unifier were what was given when you registered a new account or added a game to your company.  
    • If you have already registered these values can be found in the dashboard under Tasks->Administration->Accounts and expanding Datasets, then select your dataset.  
    • If you haven't already registered you can press the "Haven't registered yet?" button where you will be directed to the Apmetrix SignIn page where you can do so.
  • The GCM Sender ID is only needed for Android applications that use push notifications.  If your Android application is not using push notifications then you can either leave the prompt for this field as is or delete the prompt leaving the entry blank.
  • By default the Apmetrix Unity SDK does not support IDFA tracking for iOS platforms.  If your iOS application will be displaying advertisement and you would desire ad tracking then you will need to download the  Apmetrix iOS SDK from http://support.apmetrix.com/entries/23626702-Download-Apmetrix-SDK-s and replace the file "libApmetrix.a" in the "Assets/Apmetrix/Plugins/iOS" directory with the "libApmetrixWithIDFA.a" file that you just downloaded.
  • For all platforms the Child Safe permission will override previously made settings for GEO lookup, IP tracking, UDID tracking and IDFA tracking.
  • The interval at which the frame rate is automatically logged can be set by moving the slider for Frame Rate Reporting Interval to any value between 5 and 120 seconds.  By default the frame rate is automatically logged every 30 seconds. 

See the following table for more detail on the Apmetrix permission settings that can be made in the Editor:

 

Allow GEO Lookup

By default the SDK will not track GPS.

Check this permission if you wish to track Long/Lat of a customer.

*NOTE: Can be enabled for all build platforms.

Disallow UDID Tracking

Check this permission if you don't want the device's unique identifier sent to the Apmetrix server.

*NOTE: Can only be set for Android and iOS build platforms.

Make App Child Safe

 

A convenience permission that disallows GEO lookup, IP Tracking, UDID Tracking and IDFA Tracking.

*NOTE: Can be enabled for all build platforms.

Disallow DeviceID Tracking

By default the SDK will allow Device ID tracking.  

The Device ID for standalone platforms is similar to the IDFA in mobile devices.  This option is selected automatically (to disallow) if the option to make App Child Safe has been selected.

*NOTE: Can only be set for Stand Alone build platform.

Allow Pop-Up in App

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

*NOTE: Can only be enabled for Android and iOS platforms.

 

Allow IDFA Tracking

Allows the device to lookup and send to the Apmetrix 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.

*NOTE: Can only be enabled for Android and iOS platforms.

Allow URL Logging

A convenience permission that should only be set to aid non-production debug testing. 

*NOTE: Make sure this permission is not set for Production.

Offline Mode

A convenience permission that should only be set to aid non-production debug testing.  If set, all Apmetrix API methods are fully functional and the SDK is fully exercised but data collected is not sent to the Apmetrix server.

*NOTE: Make sure this permission is not set for Production. 

Setting up AndroidManifest.xml Permissions

*NOTE: If you are building to Android at this point you will need to merge your Manifest.xml file with the Manifest.xml file located in /Assets/Apmetrix/Plugins/Android/ApmetrixManifest

Take note of the Required Permissions:

You need to connect with the Apmetrix application server:

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

Determine whether the device is online or offline:

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

Determine global position (geo-location) information:

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

To enable the SDK to collect the Android Ad Id you will need to add this meta-block to your Manifest file. 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. 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. 

*NOTE: You must include the google-play-services_lib in the Assets/Apmetrix/Plugins/Android folder. You can find this folder at the following path: <android-sdk>/extras/google/google_play_services/libproject/google-play-services_lib/.  This folder can not be in a sub-folder otherwise the Android Ad Id will not be collected. 

 

3. Accessing the Apmetrix Interface Functions

To see an example of how to access the Apmetrix API, view one of the sample scenes provided.  This will require you to save the current scene you are working on first.  

  • In the Project Tab, click Assets->Apmetrix->Samples and double click TestScene to open up the Apmetrix Unity TestScene.  You'll notice the Hierarchy view includes the "[Apmetrix]" prefab game object discussed in the section Integrating the ApmetrixUnity SDK.  
  • Double click TestScene.cs to open up the script file in your IDE.
  • Viewing TestScene.cs in your IDE you'll see how an instance of the Apmetrix object was obtained in the script's Start() method.  This instance was then used when making calls into the Apmetrix API.   
  • An instance of the Apmetrix object can be obtained for each of your MonoBehavior scripts where you want to make calls into the Apmetrix API.
  • It is important the instance of the Apmetrix object be obtained in your script's Start() methods rather than the Awake() methods to guarantee the instance variable has been set before your script tries to use it.
  • Below is the example of how the Instance Object was setup for TestScene.cs.

 

4. Understanding the Apmetrix Interface Methods 

Initialize Session

*NOTE: As long as the Apmetrix script is enabled, initializing a session on startup is performed automatically when the Apmetrix script instance is loaded.  The benefits are:

  • it eases integration.
  • it eliminates error that may occur if another Apmetrix API method is called before the session is open.
  • it prevents the possibility of calling initialize session more than once.
  • timer functionality handled by the SDK when the application transitions to/from foreground and background will be handled correctly without error.

By default the [Apmetrix].prefab has the Apmetrix script enabled.  To double check that the Apmetrix script is enabled, select the Apmetrix game object in the hierarchy and in your Inspector pane make sure the enable/disable checkbox to the left of Apmetrix (Script) is checked.  It is not necessary to initialize a session again during game play.

Adding Custom Events

Call the following method in the ApmetrixWrapper GameObject to log custom events.

apmetrixObj.logEvent(int table, params string[] dimensions);

table

Predefined value for the type of Apmetrix.CustomEvent

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

Note: The layout of your custom events and their parameters is called a "Taxonomy" which is discussed by you and your Apmetrix Client Success Manager.

Integer values for the table parameter are as follows:

 (1)      ApmetrixStatic.UN_GROUPED_TABLE

The dimension data pertains to any event that cannot be put into any of the other predefined tables.

           ApmetrixStatic.USERS_TABLE

 (2)          or

           ApmetrixStatic.ACTIONS_TABLE

The dimension data pertains to any event that is triggered by the user.

 (3)      ApmetrixStatic.APPS_TABLE

The dimension data pertains to any event that is triggered by the application

 (9)      ApmetrixStatic.FTUE_TABLE

The dimension data pertains to any event that is a first time user event.

 (10)    ApmetrixStatic.ENGAGEMENT_TABLE

The dimension data pertains to any event that is related to engagement.

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 LOG EVENT EXAMPLE:

apmetrixObj.logEvent(ApmetrixStatic.TABLE_TYPE.APPS_TABLE, "verb", "object", "location", "value");

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

Dimension 1 - verb

Dimension 2 - object

Dimension 3 - location

Dimension 4 - value

Metric 1 - 1 (Metric 1 always has a value of one since it specifies how many times this event was called)

CUSTOM LOG EVENT W/ METRIC EXAMPLE:

apmetrixObj.logEvent(ApmetrixStatic.TABLE_TYPE.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 in the ApmetrixWrapper GameObject to track user interaction, logging the coordinates for a specified event at a specified location or screen:

apmetrixObj.ApTrak(string event, string location, params string[] coordinates);

Example:

apmetrixObj.ApTrak("touch", "screen1", "" + touchPosition.x, "" + touchPosition.y);

Event coordinates should be input in the following order:

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

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.

apmetrixObj.setBundleCount(int count);

Example:

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

apmetrixObj.setBundleCount(50);

In Application Purchases

Use this function 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. 

Call 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) :
apmetrixObj.inApPurchase(int quantity, string item, string location, float itemCost);

or ...

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

apmetrixObj.inApPurchase(int quantity, string item, string location, float itemCost, 
string 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 Apmetrix SetProductId() to set the internal SDK country code obtained from the SKProduct Price Locale

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.

apmetrixObj.inApPurchase(1, "100 Gem Package", "Main Screen", 2.25);

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

apmetrixObj.inApPurchase(1, "100 Gem Package", "Main Screen, 2.25, ApmetrixStatic.EUR);

Virtual Item Transaction Tracking

Call the following method in the ApmetrixWrapper GameObject to log virtual item transactions.

apmetrixObj.virtualItem(string transaction, int qty, string itemType, string location, params int[] currencies);

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. 

Examples:

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

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

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

apmetrixObj.virtualItem("Pawned", 1, "Wand of Greed", "Evil Shop", 15);

Virtual Currency Tracking

Use the following function to track the flow of virtual in-game currency.  To log a virtual currency transaction call:

apmetrixObj.virtualCurrency(string transaction, string location, params 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.

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:

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

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

Offer Tracking

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

apmetrixObj.offer(int transaction, string offerType, string location);

where

 transaction

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

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

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

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

apmetrixObj.offer(ApmetrixStatic.PRESENTED, "Weekend Sale Offer", "main menu");

 

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

apmetrixObj.offer(ApmetrixStatic.ACCEPTED, "Weekend Sale Offer", "payToRush");

 

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

apmetrixObj.offer(ApmetrixStatic.DECLINED, "Weekend Sale Offer", "cash shop");

Customer Tracking

Use the following function to track a customer ID so it can be correlated with the rest of the data being tracked on this 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 log a customer ID call:

apmetrixObj.setCustomerId(string customerId);

where

 customerId

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

Example:

The following is an example that demonstrates use of the setCustomerId() function where "123456789-98764321" is the ID the customer is identified by:

apmetrixObj.setCustomerID("123456789-98764123");

Timers

Timers for any event that you wish to track can be controlled by simply starting and stopping the timer referenced by the unique name given to the timer.  There is no need to pause or resume timers when the application goes into and out of background as that functionality is handled automatically by the SDK.  it is important to keep track of the timers that have been started so that an attempt is not made to start a timer that has already been started or end a timer that has already ended or was never started in the first place.  The following sections detail how to start and stop the timers. 

*NOTE: Pausing and resuming timers works automatically as long as the "Run In Background" Player Setting remains its default value.  If your application requires "Run In Background" to be set then an accurate accounting of timer durations is not possible because the Unity method, OnApplicationPause() will not be called.  See Run In Background for a better description of how to check this player setting.

Start Timer

Call the following method in the ApmetrixWrapper GameObject to start a new timer:

apmetrixObj.startTimer(string timerName, params string[] dimensions);

timerName

Name if the timer.  If you start a timer and that timer already exists then the system will overwrite the existing timer.

dimensions

An optional variable length comma delimited list of custom event dimensions related to this timer.  For a further explanation of how this parameter can be used see Adding Custom Events.


Examples:

apmetrixObj.startTimer("Test Timer");

or

apmetrixObj.startTimer("Test Timer", "verb", "object", "location", "#100", "#200", "#300");

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 ApmetrixWrapper GameObject to stop an existing timer:

apmetrixObj.stopTimer(string timerName);

Where timerName is the name of the existing timer. The system will only stop timers that exist.  If the existing timer had optional dimension data, it will be included with the timer name and duration when this event is sent to the Apmetrix server. 

Example:

apmetrixObj.stopTimer("Test Timer");

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

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 next level.

apmetrixObj.startLevel (string level);

 

Examples:

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

apmetrixObj.startLevel ("1");

Called when the player levels up.

apmetrixObj.startLevel ("2");

Set Location

Call this function when a player enters a new location. This is used to track a players movement in the application from one location to another and how long they spent at any particular location.

apmetrixObj.setLocation (string location);

 

Example:

Called when the player has entered the play summary screen.

apmetrixObj.setLocation ("Play Summary Screen");

Set Upload Interval

Call the following function to indicate how many minutes the SDK should wait before sending data to the Apmetrix server.

apmetrixObj.setUploadInterval(int minutes);

*NOTE: This function only applies to applications built for iOS or Android platforms.  For any other platform calls to this function return an int value of 106, (ApmetrixStatic.RETURN_STATUS.APMETRIX_WARNING_IGNORED_FUNCTION_NOT_AVAILABLE).

Example:

This example tells the SDK to wait 5 minutes between sending blocks of buffered data.

apmetrixObj.setUploadInterval(5);

Restart Session

*NOTE: For standalone applications, as long as the "Run In Background" Player Setting has not been set, restarting a session is performed automatically when the application comes back into focus (when it returns from the background).  For mobile applications the session is not ended when the application goes into the background but instead the timers are just paused.  There should be no reason or need to restart a session manually unless you have purposely ended a previous session.

If you have the "Run In Background" Player Setting set or you would like to re-start a session because you have purposely ended a previous session call the following method in the ApmetrixWrapper Game Object to re-send the device information:

apmetrixObj.restartSession();

End Session

*NOTE: For standalone applications, as long as the "Run In Background" Player Setting has not been set, ending a session is performed automatically when either the application looses focus (when it goes into the background) or when the application quits.  For mobile applications, if it is possible to know when the application is quitting, an attempt should be made to close an open session.  In cases where the mobile application quits unexpectedly or before it could exit gracefully the Apmetrix Server will flag a session as closed after a certain period of inactivity.

If you have the "Run In Background" Player Setting set or you would like to purposely close a session that is open, call the following method in the ApmetrixWrapper GameObject:

apmetrixObj.endSession();

5. Function Return Values

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

(0) ApmetrixStatic.RETURN_STATUS.SUCCESS

Successful operation.

(101) ApmetrixStatic.RETURN_STATUS.WARNING_IGNORED_SESSION_ALREADY_OPEN

Function call was ignored because a session was already open.

(103) ApmetrixStatic.APMETRIX_WARNING_IGNORED_SESSION_NOT_OPEN

A session has not been initialized

(104) (106) ApmetrixStatic.RETURN_STATUS.APMETRIX_WARNING_IGNORED_SOME_EVENT_PARAMETERS

This warning can occur when a list of parameters contains an invalid value or the number of parameters within the list is greater than allowed.  Log messages will generally detail the cause of this warning.

(105) ApmetrixStatic.RETURN_STATUS.APMETRIX_WARNING_INVALID_GCM_ID

A session has been initialized with an invalid GCM ID

(106) ApmetrixStatic.RETURN_STATUS.APMETRIX_WARNING_IGNORED_FUNCTION_NOT_AVAILABLE

The API method called is not available for the current configuration

(201) ApmetrixStatic.RETURN_STATUS.ERROR_INVALID_ARGUMENTS

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

(202) ApmetrixStatic.RETURN_STATUS.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.

(203) ApmetrixStatic.RETURN_STATUS.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) ApmetrixStatic.RETURN_STATUS.ERROR_FAILED

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

 

6. Setting up for IOS

*NOTE: If you would like to use IDFA Support you will need to include the Apmetrix Library with IDFA. Please see Windows or MACOSX downloads below.

*NOTE: In order to properly execute the ApmetrixPostprocessBuild script you will need to install Python 2.7

WINDOWS: DOWNLOAD HERE

MACOSX: DOWNLOAD HERE

Upon building for iOS, Unity will automatically call the /Editor/PostprocessBuildPlayer script. This will in-turn loop through and execute all available PostprocessBuildPlayer_* scripts.  The PostprocessBuildPlayer_Apmetrix script will call the ApmetrixXcodeUpdatePostBuild.pyc, which will automatically import the following frameworks into your Unity-iPhone.xcodeproj:

The build script will add the following frameworks and linker-flags:

Linker-Flags:

  • -weak_framework
  • CoreMotion
  • -weak-ISystem
  • -ObjC
  • -lsqlite3.0

Frameworks:

  • libsqlite3.0.dylib
  • Foundation.framework
  • SystemConfiguration.framework
  • CoreLocation.framework
  • StoreKit.framework

This allows you to build and run your iOS projects, without needing to stop and change any settings for Apmetrix integration.  The ApmetrixXcodeUpdatePostBuild.log will be available in your project folder to look at the results of the update to your xcode project.

 

7. Run In Background

Automatic pause and resume of timers / end and restart of sessions is dependent on the "Run In Background" Player Setting NOT being enabled.  "Run In Background" setting can be checked by reviewing the Player Settings.  In the IDE click Edit->Project Settings->Player.  In the Player Settings inspector pane find Resolution and Presentation.  See the figure below:

If there is a need to enable "Run In Background" then sessions will remain open when the application goes into the background and timer values will not be accurate because they will include that period of time the application was inactive.

8. Additional Information

This section re-iterates some of the things that the Unity SDK does automatically. These are all located in the Apmetrix.cs file and can be changed to fit your needs. This code can be found in the Start(), OnApplicationQuit() and OnApplicationPause(bool state) methods.

  • The SDK automatically inits an Apmetrix Session and resumes all paused timers (if there are paused timers) when your app starts up as long as the Apmetrix.cs script is enabled.  See Setting the Static Apmetrix Variables for details on how this is checked.
  • When your app quits, goes into the background or loses focus (the user interacts with another application) the SDK automatically pauses all active timers. This is dependent upon "Run In Background" not being set.
  • When your app returns to the foreground the SDK resumes all paused timers (if there are paused timers).  This is also dependent on "Run In Backgound" not being set.
  • The SDK will delay app shutdown to allow an end session event and any buffered ApTrak data to be sent to the Apmetrix server before finally quitting the application.  The delay of app shutdown though is only possible when the application is NOT running in editor. 
Have more questions? Submit a request