iOS SDK

Overview

You must integrate and implement the Digital Analytics SDK for iOS before you can use digital Analytics to generate reports on the activity of visitors to your iOS application.

Before you begin

To get started, see Digital Analytics SDK for iOS overview for the following information:

• SDK improvements to the SDK.
• Supported versions for iOS, Android, Apple Xcode, and Swift.

Integrate the SDK into your iOS application

Following is the list of files that you need to integrate the Acoustic Digital Analytics SDK. They are part of the release package that is provided with the SDK.

1. If you already have the Digital Analytics subgroup, delete everything from the subgroup then use the Cmd+Opt+Shift+K command to deep clean your Xcode project.
2. Create a subgroup in your project called Digital Analytics.
3. If you already have the Digital Analytics subgroup, delete everything from the subgroup.
4. Drag (or copy) the package contents into your iOS project folder under the Digital Analytics subgroup.
5. Go to Build Phases of your iOS Project target and verify the following items for each target in your project:

• DAMod.framework and libEOCore.a are listed under Link Binary with Libraries before any of the Apple iOS frameworks.
• DAMod.bundle and EOCoreSettings.bundle is listed under Copy Bundle Resources.

6. You can use the BasicConfig.plist file to customize the SDK behavior. It is unlikely that you need to modify the other files in this list.

7. Go to Your Project Settings> All of Your Project Targets > Build Phases > Link Binary With Libraries. Add the following libraries. You can skip this step if these items are already added to your project.

📘

Note:

List these libraries before any Apple libraries. If you list them after the Apple libraries, your application may not pass the App Store approval process.

• SystemConfiguration.framework
• libz.dylib (for iOS 8.0 and earlier) or libz.tbd (for iOS 9.0 and later)
• CoreTelephony.framework
• UIKit.framework
• Foundation.framework
• CFNetwork.framework
• CoreGraphics.framework

8. Go to Project Settings > Build Settings > Other Linker Flags and add the -ObjC flag.

(Optional) If your application is written in Swift, integrate the Swift2 application

Integrate the Swift2 application with the Digital Analytics SDK.

1. Create a header file and name it DigitalAnalyticsBridgingHeader.h.
2. Import DAMod/DigitalAnalytics.h into the header file.
3. Add the newly created DigitalAnalyticsBridgingHeader.h header file to your project settings.

• Select your project in XCode.
• Click Build Settings and find Objective-C Bridging Header.
• Set the value of Objective-C Bridging Header to DigitalAnalyticsBridgingHeader.h.

4. Open the app delegate file of your application and locate the didFinishLaunchingWithOptions function and call DigitalAnalytics.startup() from there or from another suitable location.
5. Locate the applicationWillTerminate function and call DigitalAnalytics.shutdown() from applicationWillTerminate or from another suitable location.
6. Call the Digital Analytics fireXXX APIs from any appropriate location after DigitalAnalytics.startup() is called the first time. For more information, refer to Extracting data from reports using the Digital Analytics API.

Add network information to your Info.plist file

Due to the new way iOS 9.0 and 9.1 handle network connections, you need to add NSAppTransportSecurity information. Add the following information to your Info.plist file. For more information, refer to Apple documentation on NSAppTransportSecurity.

<key>NSAppTransportSecurity</key>
<dict> 
 <key>NSExceptionDomains</key>
 <dict> 
 <key>coremetrics.com</key>
 <dict> 
 <key>NSIncludesSubdomains</key>
 <true/>
 <key>NSExceptionAllowsInsecureHTTPLoads</key>
 <true/> 
 <key>NSExceptionMinimumTLSVersion</key> 
 <string>TLSv1.0</string>
 </dict>
 </dict>
</dict>

Enable the debug log

Use this procedure to enable the debug log for the Digital Analytics application.

1. Select Run to edit your project scheme.
2. Under Environment Variables, add DIGITAL_ANALYTICS_DEBUG and set its value equal to 1.
   When you run your project, you see Digital Analytics logs in your console window.

Start the SDK

Find a suitable place in your application call flow to start the Digital Analytics SDK. Typically it would be one of the following locations:

• Where your application starts
• Where the application comes to the foreground
• Where you want to start using the Digital Analytics

If you decide to start the Digital Analytics SDK from when your application starts, place this call following the Digital Analytics API:

- (BOOL)application:(UIApplication *)
 application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 
{ 
 if( [DigitalAnalytics startup] ) 
 { NSLog(@"DigitalAnalytics SDK started"); 
 } 
 else 
 { 
 NSLog(@"DigitalAnalytics SDK failed to start"); 
 } 
}

Stop the SDK

1. Find a suitable place in your application call flow to stop the Digital Analytics SDK. Typically it would be one of the following locations:

• Where your application stops
• Where the application comes to the foreground

If you decide to stop the Digital Analytics SDK where the application stops, place this call following the Digital Analytics API:

- (void)applicationWillTerminate:(UIApplication *)application {

	[DigitalAnalytics shutdown];
}

Manage sessions for iOS applications

Use the following methods to manage sessions for iOS applications.

startNewSession method for iOS
This method call ensures that additional methods are associated with the same session.

In the Digital Analytics system, there is a concept of a session that is associated with a set of tags that are fired during the lifetime of that session. It is up to the application to decide how to demarcate the sessions, but the Digital Analytics SDK API provides a clear way to differentiate one session from another. Typically, at the start of a new session, before starting any fire API method calls, the developer starts the following method:

[ DigitalAnalytics startNewSession ];

When it is time in your application to start another session with a new set of Tags, start the [ DigitalAnalytics startNewSession ]; method again.

visitorID method for iOS
Use this method to get the session ID associated with the currently active tag session. The session ID will change across the creation of new tag sessions.

[ DigitalAnalytics sessionID ];

session ID method for iOS
Use this method to get the session ID associated with the currently active tag session. The session ID will change across the creation of new tag sessions.

[ DigitalAnalytics sessionID ];

Customize tag post default behavior for iOS

By default, tags are put in a queue and processed every 30 seconds. When a tag is fired, the SDK engine collects the tag data and places it in a queue to be submitted to the server. By default, this queue service runs every 30 seconds. If the queue server finds tag data, it submits it in the background. This behavior makes more efficient use of system resources by not activating a network process for each tag. This is the default behavior.

You can modify tag post-default behavior by using the BasicConfig.plist file in EOCoreSettings.bundle.

1. Locate the BasicConfig.plist file in EOCoreSettings.bundle.
2. Modify one of the following parameters:

Configure the Digital Analytics client ID

The dynamic client ID feature allows you to change the Digital Analytics client ID to a different value depending upon the context in which the application is executing.

For example, if your application is linked to two different businesses, those businesses will need to collect data separately using two separate client IDs. Use this feature to ensure that user activity associated with each business is sent to the correct client ID. You configure the default client ID in the BasicConfig.plist file.

Override the default client ID
You can override the default client ID that is defined in the BasicConfig.plist file by invoking the following method:

DigitalAnalytics class API +(BOOL)activateClientId:(NSString*)newClientId

where newClientId is a new client ID. After this method is started, all tags that are run are associated with the new Client ID value rather than the default value.

Return to the default client ID
If you override the default client ID, you can return to the default client ID that is defined in the BasicConfig.plist file by starting the following method:

DigitalAnalytics class API +(BOOL)resetToDefaultClientId

After this method is started, all tags that are run are associated with the default value that is defined in the BasicConfig.plist file.