Overview

Skill Level: Intermediate

Prerequisites

To get started, review the following information from the IBM Tealeaf iOS SDK supported platforms and system requirements:

  • Installation package contents
  • Log screen layout for iOS mobile app session replay
  • Hardware and software requirments
  • Impact on device resources

After you download the Tealeaf iOS SDK package, you install the iOS SDK libraries into an iOS application project. You can use the iOS SDK with Objective C using this tutorial. Or you can integrate with Swift using this tutorial: Getting started with the IBM Tealeaf SDK for iOS using Swift.

Step-by-step

  1. Add required iOS frameworks to your Xcode project.

    The iOS Logging Framework requires these frameworks:

    • Foundation.framework
    • UIKit.framework
    • WebKit.framework (for iOS version 8 and later)
    • CoreGraphics.framework
    • CoreLocation.framework
    • CoreTelephony.framework
    • libz.dylib (For use with iOS version 8)
    • libz.tdb (For use with iOS version 9 and later)
    • SystemConfiguration.framework
    • WebKit.framework

    If these frameworks are already in your project, you do not need to add them a second time. Otherwise, complete the following steps:

    1. In your Xcode project, select the project node in the Project Navigator.
    2. Select your desired target under the targets list.
    3. Select the General tab.
    4. In Linked Frameworks and Libraries, click + to search and select frameworks.
  2. Add IBM Tealeaf files to your Xcode project.

    Note: If you are upgrading your iOS SDK from a version of the iOS SDK that is earlier than 10.1.0, complete the following steps first:
    1. Remove the following header files from your Xcode project:
      • TLFApplication.h
      • TLFApplicationHelper.h
      • TLFCustomEvent.h
      • TLFPublicDefinitions.h
    2. Delete libTLFLib.a and all TLF*.h files.
    3. Move TLFResources.bundle out of the project and on to the Desktop.

    Adding the Tealeaf files

    1. Drag EOCoreSettings.bundle, libEOCore.a, and EOApplicationHelper.h from TealeafMod > EOCore > Debug-Headers to the main target folder for your project.
    2. Drag Tealeaf.framework and TLFResources.bundle from TealeafMod > Tealeaf > Debug to the main target folder for your project.
    3. From your project, select Build Phases > Link Binary With Libraries.
      Add the following libraries:

      Note: The following libraries should be listed before any Apple libraries, for example the SystemConfiguration.framework and UIKit.framework libraries. If the following libraries are listed after the Apple libraries, your application might not pass the App Store approval process.
      • libEOCore.a
      • Tealeaf.framework
      • libz.dylib (For use with iOS versions 8.)
      • libz.tdb (For use with iOS version 9 and later.)
      • SystemConfiguration.framework
      • Foundation.framework
      • UIKit.framework
      • WebKit.framework (for iOS version 8 and later)
      • CoreGraphics.framework
      • CoreTelephony.framework
      • CoreLocation.framework
      • CFNetwork.framework
    4. From your project, select Build Phases > Copy Bundle Resources. Add TLFResources.bundle and EOCoreSettings.bundle.
  3. Instrument the iOS SDK into your project.

    1. From your Xcode project, select iOS Source > Cocoa Touch Class > Create yourproject-Prefix.pch.
      Note: yourproject-Prefix.pch is the precomputed header for the #import libraries.
    2. If you are upgrading your iOS SDK from a version of the iOS SDK that is earlier than 10.1.0, remove the existing Tealeaf #import statements. Old Tealeaf #import statements are typically found in quotation marks (“”) instead of angle brackets (<>).
    3. Add the following text to the #import statement:
      Note: ASIdentifierManager.h is required if you want your application to capture Apple identifier for advertisers (IDFA) data using the Tealeaf AdvertisingId property.
      #import <UIKit/UIKit.h>
      #import <Foundation/Foundation.h>
      #import <Tealeaf/TLFApplication.h>
      #import <Tealeaf/TLFApplicationHelper.h>
      #import <Tealeaf/TLFCustomEvent.h>
      #import <Tealeaf/TLFPublicDefinitions.h>
      #import <AdSupport/ASIdentifierManager.h>
    4. From your Xcode project, select Build Settings > Prefix Header and add yourprojectname\yourproject-Prefix.pch.
    5. Set the Objective-C linker flag.
      1. In Xcode, go to the Build Settings for your project and select the main Target.
      2. In the search box, enter Other Linker Flags.
      3. If the -ObjC flag is not listed as an Other Linker Flags entry, double-click the row and select the +, then enter -ObjC. If the -ObjC flag is listed, you are done with this task.
    6. Edit PostMessageUrl in TealeafBasicConfig.properties to point your target server.
    7. Initialize TLFApplication, and pass the reference to UIApplicationMain by adding the following code snippet to main.m:
      NSString *tealeafSDK = 
      NSStringFromClass([TLFApplication class]);
      return UIApplicationMain(argc, argv, tealeafSDK,
      NSStringFromClass([AppDelegate class]));
    8. Enable the Tealeaf framework in your appDelegate.m.
      Note: If DynamicConfigurationEnabled in EOCoreBasicConfig.plist is set to NO, you do not have to complete this task.

      1. In Xcode, locate your app delegate file.
      2. Search for this code:
        (BOOL)application:(UIApplication *)application 
        didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
      3. If you are using the AdvertisingId to capture Apple identifier for advertisers (IDFA) data, add the following code snippet to the top of your application.
        [[TLFApplicationHelper sharedInstance] setCXAAdvertisingId:[[[
        ASIdentifierManager sharedManager]advertisingIdentifier] UUIDString]];
      4. Add the following code snippet as the second line of the method application
        Note:
        If you are not capturing IDFA data, add the code snippet to the top of your application.
        didFinishLaunchingWithOptions:

        [[TLFApplicationHelper sharedInstance] enableTealeafFramework];
        
    9. Configure how screen layouts are logged, target-page location, kill-switch location, and whether gestures are logged. For more information, see Configuring the IBM Tealeaf SDK for iOS.
    10. If you are upgrading your iOS SDK from a version of the iOS SDK that is earlier than 10.1.0, transfer your configuration settings from Reconfigurations.properties to TealeafBasicConfig.properties.
  4. Set the UIApplication Class to use the Tealeaf Application class or modify your custom UIApplication class.

    The changes that are needed in the code depend on whether your project implements a custom UIApplication Class.

    No custom UIApplication class

    If your application does not have its own custom UIApplication class, you can use the IBM Tealeaf UIApplication class.

    Custom UIApplication class

    If your application has its own custom UIApplication class (for example, named CustomerUIApplication), but there are no sendAction and sendEvent methods in CustomerUIApplication class, review the following information.

    If your application has its own custom UIApplication class (for example, named CustomerUIApplication), and there are sendAction and sendEvent methods in CustomerUIApplication class, you can add code to point to the  Tealeaf sendAction and sendEvent classes.

    Using the TLFApplication class

    If your application does not have its own custom UIApplication class, it can use the¬† Tealeaf iOS SDK TLFApplication class. In your application’s main.m file, you must tell UIApplicationMain to use the¬† Tealeaf subclass of UIApplication.

    1. In your main.m class, search for code that uses the UIApplication:
                return UIApplicationMain(argc, argv, nil, NSStringFromClass
      ([AppDelegate class]));
    2. Replace the third argument, nil, with the name of the TLFApplication class. The line should now look like;
                return UIApplicationMain(argc, argv, NSStringFromClass
      ([TLFApplication class]), NSStringFromClass([AppDelegate class]));

    Modifying the custom UIApplication class

    If your custom class does not have sendAction and sendEvent methods, you can add them. If your custom class does have sendAction and sendEvent methods, you can modify them to point to the  Tealeaf methods. The Tealeaf methods have logging built into them.

     
    1. Optional: If your UIApplication class does not have sendAction and sendEvent classes, add the sendAction and sendEvent methods to your custom UIApplication class. For example:
      @implementation CustomerUIApplication
      - (void)sendEvent:(UIEvent *)event
      {
      [[TLFApplicationHelper sharedInstance] sendEvent:event];
      [super sendEvent:event];
      }
      - (BOOL)sendAction:(SEL)action to:(id)target from:(id)sender forEvent:
      (UIEvent *)event
      {
      [[TLFApplicationHelper sharedInstance] sendAction:action to:target
      from:sender forEvent:event];
      return [super sendAction:action to:target from:sender forEvent:event];
      }
    2. Optional: If your custom UIApplication class has sendAction and sendEvent methods, modify the methods to point to IBM Tealeaf sendAction and sendEvent. For example, add this line to the sendEvent method:
      [[TLFApplicationHelper sharedInstance] sendEvent:event];

      For example, add this line to the sendAction method:

      [[TLFApplicationHelper sharedInstance] sendAction:action to:target from:sender forEvent:event];
  5. Use the IBM Tealeaf Image Extractor to push image files to the Replay server

    The IBM Tealeaf Image Extractor is included with the  Tealeaf iOS SDK and can be used to extract images from your mobile application and upload them to the Replay server.

    When using  Tealeaf to capture a mobile session, images from the mobile application are sent to the  Tealeaf server. If the images from the mobile application are already stored on the Replay server, the mobile application does not upload the images during an active session. Uploading the images to the Replay server reduces the amount of data that is sent from the mobile device and can display the images when you replay a native mobile session.

    Running the Image Extractor utility extracts the images from your project source, hash the image names from your project source, and replace the image names in your project source with the new hashed names. After the Image Extractor finishes processing, copy the hashed images to the Replay server.

    To run the Image Extractor:

    1. Open TLFImageTool.app.
    2. Select Source and enter or select the path for the project source you are using to create your mobile application; then, select Choose.
    3. Select Destination and enter the path where you want to store the hashed images that are extracted from your project; then, select Choose.
    4. Select Extract Images to Destination to process the source project and extract the images from the project. The image extractor hashes the image names from your project source and replaces the image names in your project with the new hashed image names.
    5. After the Image Extractor finishes processing, copy the hashed images from the folder you specified in step 3 to the Replay server.

    Extracting PDF Vector Images in an iOS project

    You can set a PDF image to UIImageView through storyboard or programmatically.

    There are two ways to set a PDF image to UIImageView:

    • Programmatic approach
    • Through storyboard

    If the PDF image is set to UIImageView programmatically, no additional steps are needed to extract the images.

    However, if the PDF image is set to UIImageView through storyboard, additional steps are needed to extract that image:

    • Set a user defined run-time attribute for the UIImageView with the key as tlfFileReference and the name of the PDF image as the value.
    • Now run the Image Extractor tool. You should see the PDF images along with other images in your designated folder.

    User defined run-time attributes can be defined for any NSKeyValueCoding protocol compliant object using either of the following ways:

    • Select the desired element (UIImageView instance in this case) in the storyboard and open Identity Inspector. Go to the User Defined Runtime Attributes section and add a new property.
    • Set programmatically by calling setValue:forKeyPath: method of the object (UIImageView instance in this case) in the viewDidLoad: method of the object’s UIViewController.
  6. Upload images to Replay

    1. Rename your “images” folder to “replayImages” and zip this folder.
    2. On your Replay portal, go to the Organization tab and click on Manage Accounts.
    3. Click on the Company Settings tab.
    4. Scroll until you see Image package.
    5. If a timestamp is present, click on the timestamp to download all the images folder from the organization.
    6. Unzip the downloaded folder.
    7. Add the contents of the “image” folder.
    8. Zip it back up and name it imagesReplay.zip.
    9. On the portal, click on Edit at the bottom right corner of the page.
    10. Click on Change the file by the timestamp for the Image package.
    11. Click Browse, select the imagesReplay.zip folder from your machine, and click Upload.
    12. Important: Wait until the timestamp changes. Only after the timestamp changes, click Save.
    13. Return to your session, your images should display now.

Expected outcome

The Tealeaf iOS SDK for apps developed with iOS Objective C is installed.

Next, configure the Tealeaf SDK for iOS. For information, see Configuring the IBM Tealeaf SDK for iOS.

Join The Discussion

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