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 Swift using this tutorial. Or you can integrate with Objective C using this tutorial: Getting started with the IBM Tealeaf SDK for iOS using Objective C.

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. Create a bridging header file if your project does not have one.

      1. Create a bridging header by choosing File > New > File > (iOS, watchOS, tvOS, or macOS) > Source > Header File and name your file as “<ProjectName>/<ProjectName>-Bridging-Header.h”.
      2. If Xcode offers to create an Objective-C bridging header file, accept it. Otherwise, navigate to your project build settings and find the “Swift Compiler – Code Generation” section. You may find it faster to type “Swift Compiler” into the search box to narrow down the results.
      3. Next to “Objective-C Bridging Header”, you will need to add the name/path of your header file. If your file resides in your project’s root folder, simply put the name of the header file there.

        Examples: “<ProjectName>/<ProjectName>/-Bridging-Header.h” or simply “<ProjectName>-Bridging-Header.h”.
      4. Open your newly created bridging header and import your Objective-C classes using #import statements. Any class listed in this file will be able to be accessed from your Swift classes.

        Note:If the project already has a bridging header file and 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 (<>).

    2. Add the following import statements to the bridging header file:
      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>
    3. 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.
    4. Edit PostMessageUrl in TealeafBasicConfig.properties to point your target server.
    5. 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.
    6. 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. Integrate the iOS SDK with a Swift iOS application.

    The same headers, library, and resources for an Xcode project are also used for Swift projects. Swift projects use Tealeaf-Bridging-Header.h as the prefix header (bridging header) file.

    Continue integrating the iOS SDK with Swift:

    1. Open the AppDelegate.Swift file and search for the didFinishLaunchingWithOptions function.
    2. Add this code to the didFinishLaunchingWithOptions function:
      //Tealeaf
      let tlfApplicationHelperObj = TLFApplicationHelper()
      tlfApplicationHelperObj.enableTealeafFramework()
      //Tealeaf End
    3. If you want your application to capture Apple identifier for advertisers (IDFA) data using the Tealeaf AdvertisingId property, add the following code snippet in place of the code added in the previous step (the didFinishLaunchingWithOptions function):
      TLFApplicationHelper.sharedInstance().setCXAAdvertisingId(ASIdentifierManager.shared().advertisingIdentifier.uuidString)
      TLFApplicationHelper.sharedInstance().enableTealeafFramework()
    4. Go to Edit Scheme > Arguments > Environmental Variables.
    5. Add the debug variable TLF_DEBUG, EODebug and set the variable value to 1.
    6. Compile your code and run the application.
  5. Subclass the UIApplication to track UI control events.

    Subclassing the UIApplication allows the UI control events to be tracked by the SDK.

    1. In your Swift application, open the AppDelegate.swift file and comment out the @UIApplicationMain line.
    2. Override the sendAction and sendEvent methods: and add this code to the file:
      1. Create a HelloSwiftApplication.swift file.
      2. Add this code to the file:
        import Foundation
        class HelloSwiftApplication: UIApplication {
        override func sendEvent(event: UIEvent){
        let tlfApplicationHelperObj = TLFApplicationHelper()
        tlfApplicationHelperObj.sendEvent(event)
        super. sendEvent(event)
        }
        override func sendAction(action: Selector, to target:
        AnyObject!, from sender: AnyObject!,
        forEvent event: UIEvent!) -> Bool{
        let tlfApplicationHelperObj = TLFApplicationHelper.sharedInstance()
        tlfApplicationHelperObj.sendAction(action, to:
        target, from: sender, forEvent: event)
        return super. sendAction(action, to: target, from:
        sender, forEvent: event)
        }
        }
    3. Subclass the UIApplication:
      1. Create a main.swift.
      2. Add this code to the main.swift file:
        import Foundation
        import UIKit
        UIApplicationMain (Process.argc, Process.unsafeArgv, NSStringFromClass (HelloSwiftApplication),
        NSStringFromClass(AppDelegate))
    4. Open the Info.plist file and add this line: Key “Principal Class” with value: “HelloSwiftApplication”.
  6. 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.
  7. 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 Swift 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 *