Follow

Integrating the Apple watchOS (Xcode) SDK

 

Table of Contents:

Apmetrix Apple watchOS Integration

Apmetrix Apple Watch SDK Functions

Integrating the Apple watchOS Framework

The following simple steps explain how to integrate our Apple watchOS framework into your game or other mobile application.

STEP 1 – Add the ApmetrixWatch framework file to your iOS project.

STEP 2 – Link ApmetrixWatch framework library to your iOS & watchOS project.

Click on project name in the left hand column of XCode, then select target as WatchApp Extension and then select Build phases tab in the middle screen. Select the Link Binary With Libraries section. Click on the + sign to add framework. You will need to add the following:

ApmetrixWatch.framework

STEP 3 – Interface with the ApmetrixWatch framework in your project.

In the project Extension delegate file or anywhere else where you need to use the Apmetrix watchOS specific API functions, use the following import statement:

import ApmetrixWatch

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 ApmetrixWatch SDK framework. You can now set up and call the various functions you need to the Apmetrix analytics platform.

Apmetrix WatchOS SDK Functions

All SDK functions are class methods for the Apmetrix class.

1. INITIALIZE APMETRIX  WATCH SESSION - Initialize session between WatchApp and iPhone Application (Parent application).

Function: Apmetrix.initializeApmetrixWatchSession(session: WCSession?)
session WCSession Object

2. INITIALIZE SESSION – Initialize (i.e. start an app session).

Note: This function will be ignored if the parent application running on the phone has started the application session first.  Likewise if either of the following functions are called before the parent application tries to start an application session then the function called from the parent application will be ignored:

To start an app session using the default permissions use:

Function: Apmetrix.initWithDataset(gameDataSet:Int,andVersion:String,
andUnifier:String)

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

Function: Apmetrix.initWithDataset(gameDataSet:Int,andVersion:String,
andUnifier:String,andPermissions:tPermission?)

where: 

 gameDataSet

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.

 andVersion

String that identifies the version of the application.

 andUnifier

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

 andPermissions

Optional parameter that when used defines the permissions/restrictions on the application.

This parameter is a tPermission enum type where multiple permissions can be set by "ORing" their values together.  If a "nil" value is used for this parameter the SDK defaults to NO_GEO_LOOKUP.

and where 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_AD_ID

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. 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 only in the SDK that is linked with the parent application.  In addition it is 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 either of the other two versions of the iOS SDK (libApmetrix.a or libApmetrixNoReach.a).  Applications that include IDFA code when they don't include ad functionality run the risk of being rejected when they are submitted to the App Store for review.   

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

3.END SESSION – To end WatchApp session use the following command:

Function: Apmetrix.endSession()

4. RESTART SESSION - To restart WatchApp session use the following command:

Function: Apmetrix.restartSession()

5. LOG CUSTOM EVENT - To log custom event data or dimensions use either of the following functions:

Function: Apmetrix.logEvent(eventName:String, andEventData:[String:String])

or

Function:Apmetrix.logEvent(table:tTable, andDimensions:String ...)

where:

 eventName

Event name to be logged.

 eventData

Event data to be logged.

 table

Predefined value for the type of Apmetrix event.

 dimensions

Variable length comma delimited list of custom event dimensions.

and where optional values for tables are:

 OTHER

 These are any custom events which are not covered under any of the other tables (e.g. exceptions, crashes, etc.)

 ACTIONS

These are any custom events which are triggered by the user (e.g. clicks on account settings, opens level map, completes level, completes registration, etc.)

 APPS

 These are any custom events triggered by the App (e.g. App creates a local notification, App goes into background, App comes into foreground, etc.)

 FTUE

 These are any custom events that are a first time user experience (e.g. first time visits website, first time purchase, first time launches App, etc.)  

 ENGAGE

 These are any custom event related to engagement (e.g. shares a post, invites a friend, logins into Facebook/Twitter/etc., sends a gift, etc.) 

6. LOG ONE TIME EVENT - To log one time event

Function: Apmetrix.logOneTimeEvent(table:tTable,andTag:String, dimensions:String ...)

where:

 table

Predefined value for the type of Apmetrix.CustomEvent.

 tag

Name identifying this one-time event.

 dimensions

Variable length comma delimited list of custom event dimensions.

7. START EVENT TIMER - To start an event specific timer use the following function:

Function: Apmetrix.startTimerForEvent(event:String)

where:

 event

Identifies the event to start timing.

8. STOP EVENT TIMER - To stop a previously started event specific timer use the following function:

Function: Apmetrix.stopTimerForEvent(event:String)

where:

 event

Identifies the event to stop timing and thus log the event's duration.  You can only stop the timer for an event that had previously been started (i.e. the parameters strings must be identical) 

9. TRACKING USER INTERACTION – To log coordinates of user events on specific screens use.

Function: Apmetrix.ApTrak(event:String, andLocation:String, andCoordinates:String ...)

 event

Identifies the event being logged.

 location

Identifies the location or screen the event occurred on.

 coordinates

List of coordinate for the event ordered as X,Y,[Z] and [W](Where X and Y are required and Z and W are optional).

10. SEND REQUEST – Call this function to log custom event.

Function: Apmetrix.sendRequest(requestData:[String:AnyObject])

where

 requestData

Dictionary of custom events.

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

Function: Apmetrix.startLevel(levelName:String)

Example:

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

Apmetrix.startLevel(“Level 1”)

Call when the player levels up.

Apmetrix.startLevel(“Level 2”)

12. PAUSE EVENT TIMERS – To pause all watch event timers when your watch application has resigned active use the following function:

Function: Apmetrix.appDidEnterBackground()

Note: It is suggested that this function be called from your watch extension delegate's applicationWillResignActive() method. Failure to call this method, or calling it from the wrong delegate method may result in incorrect watch event durations.

13. RESUME EVENT TIMERS - To resume all watch event timers that had previously been paused when the watch application resigned active, use the following function:

Function: Apmetrix.appWillEnterForeground()

Note: It is suggested that this function be called from your watch extension delegate's applicationDidBecomeActive() method. Failure to call this method, or calling it from the wrong delegate method may result in incorrect watch event durations.

14. SET CUSTOMER ID - Use this function 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 log a customer ID call.

Function: Apmetrix. setCustomerId(customerId:String)

where

customerId

Identifies the user playing the game or logged onto the app.

Note: If setting the customer ID with this function it must be done prior to initializing the session with a call to initWithDataset(). 

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

15. SET AP TRAK BUNDLE COUNT - 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. setApTrakBundleCount(maxCount:Int)

Note: If setting the ApTrak bundle count with this function it must be done prior to initializing the session with a call to initWithDataset() 

Example:

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

Apmetrix.setApTrakBundleCount(50)

16. 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(minutes:Int)

where

minutes

Minutes to wait before sending data to server.

Note: If setting the upload interval with this function it must be done prior to initializing the session with a call to initWithDataset() 

Example:

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

Apmetrix.setUploadInterval(5)
Have more questions? Submit a request