Overview

Skill Level: Intermediate

Prerequisites

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.¬†

Before you begin, download the SDK by using the SDK Manager. Depending on your OS, following these tutorials before integrating the Digital Analytics SDK:

Step-by-step

  1. Integrate the SDK into your iOS application.

    Following is the list of files that you need to integrate the IBM¬ģ Digital Analytics Software Development Kit (SDK). They are part of the release package that is provided with the SDK.

     File  Folder location
     DAMod.framework /DigitalAnalytics/DAMod
     DAMod.bundle /DigitalAnalytics/DAMod
     libEOCore.a /DigitalAnalytics/EOCore
     EOCoreSettings.bundle /DigitalAnalytics/EOCore
    1. If you already have the IBM 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 IBM Digital Analytics.
    3. If you already have the IBM Digital Analytics subgroup, delete everything from the subgroup.
    4. Drag (or copy) the package contents into your iOS project folder under the IBM 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 are 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.
       Name Value
       PostMessageUrl

      URL of the Host where tag data must be sent. By default, it is set to the test data warehouse at: https://testdata.coremetrics.com/cm

      To send data to the production server, change this value to https://data.coremetrics.com/cm

      ¬†ClientId ClientId uniquely identifies the client sending the tag data. In case of multiple clients the client IDs, the ID values must be concatenated and separated by a delimiter. Use the ‚Äė;‚Äô character between 8-digit ID values and the ‘|’ character between Multisite Global Id and SiteId values.
      Example sending data to a single 9-series ID: 99999991
      Example sending data to multiple 9-series IDs:
      “99999991;99999992;99999993”
      Example sending data to a single Multisite ClientId with accompanying SiteId value:
      59999999|SiteId
      Example sending data to multiple Multisite ClientIds with accompanying SiteId values:
      59999991|SiteId;59999992|SiteId;59999993|SiteId
       AppName Name of the Application. 
       CaptureAllOfflineTags Specify true to capture all tags when the App is offline. Specify false to restrict this capturing to only 10 tags. True is the default.
    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.
  2. (Optional) If your application is written in Swift, integrate the Swift2 application.

    Integrate the Swift2 application with the IBM¬ģ 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.
      • Selecting your project in the XCode left pane.
      • Clicking 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 toExtracting report data with the Digital Analytics API.
  3. Add network information to your Info.plist file

    Due to a 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>
  4. Enable the debug log.

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

    1. Edit your project scheme, selecting Run in left pane.
    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.

  5. Start the SDK.

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

    • Where your application starts
    • Where the application comes to 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");
    }
    }
  6. Stop the SDK.

    1. Find a suitable place in your application call flow where to stop the Digital Analytics SDK. Typically it would be one of the following locations:
      • Where your application stops
      • Where the application comes to foreground
    2. 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];
    }
  7. 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 life time 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 visitor ID associated with the user of the application. The visitor ID remains the same across multiple invocations of this method.

    [ DigitalAnalytics visitorID ];

     

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

     

  8. 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:
       Parameter  Options
       ManualPostEnabled  

      No – tag data is placed in a queue to be processed based on the PostMessageTimeInterval value. This is the default value.

      Yes – tag data is processed for every tag. With this value, tags are posted immediately, but uses more system resources. Because of the system resource requirements for this setting, use this setting only if your application requires tags to run immediately.

       PostMessageTimeInterval  The number of seconds the tag queue service waits to submit tags. The default is 30 seconds.
  9. 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. For information, refer to substep 6 of Step 1 of this tutorial.

     

    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 invoked, all tags that are executed 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 invoking the following method:

    DigitalAnalytics class API +(BOOL)resetToDefaultClientId

     

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

     

     

Expected outcome

The Digital Analytics SDK for iOS is integrated and implemented.

Join The Discussion

Your email address will not be published. Required fields are marked *