Overview

Skill Level: Any

This tutorial describes the basic steps to configure the Tealeaf and Windows based servers to capture and process data that is submitted from the iOS SDK.

Prerequisites

Before getting started, ensure that you install and implement the Tealeaf SDK for iOS by following these instructions:

 

 

 

Step-by-step

  1. Configure data privacy.

    IBM Tealeaf provides mechanisms for masking or blocking sensitive customer information, such as credit card numbers, from being transmitted and captured by IBM Tealeaf.

    Through the iOS SDK, you can specify the fields that must be blocked or masked in your web application. When applied, data privacy ensures that these data elements are never transmitted to IBM Tealeaf.

    Note: Due to the way in which client framework data is submitted to IBM Tealeaf for capture, to mask or block sensitive data you apply filtering through the capturing client framework. While other IBM Tealeaf features to manage data privacy can be deployed, they are not easy to implement on the format of data captured from the client frameworks.
  2. Add a target page to your web server environment to which the iOS SDK can submit posts.

    IBM Tealeaf is designed to capture traffic between a client and a web server. To facilitate capture, you add a target page to your web server environment to which the iOS SDK can submit posts.

    After you add the target page to your web environment and enable the appropriate access permissions, you must configure the URL for the target page in the TLFConfigurableItems.plist page. You can test the basic functionality of the target page by triggering GET and POST actions on the URL where the target page was installed.
    Note: If needed, you can configure the client framework to submit by HTTPS by adding the protocol identifier to the POST URL.

     
  3. Configure a sampling function that manages traffic volume.

    You can add a sampling function to work with the iOS SDK kill switch. This sampling function can be used to throttle the sampling rate and thus the volume of traffic that is forwarded for capture.

    For more information about sampling functions for various server environments, see Sample code.

  4. Implement screenViews.

    For pages in which the state or context can be switched without re-rendering the page, IBM Tealeaf segments the data between states by using an object that is called a screenView. For example, if a page contains multiple tabs in it, each of which represents a different stage in a checkout process, you instrument each tab in the page as a distinct screenView.

    To implement a screenView for a page, complete the following steps.

    1. logicalPageName for a screenView is the current UIViewController’s classname or title.
    2. If the prior step is not completed, call [TLFCustomEvent sharedInstance] logAppContext and pass the logicalPageName. For example:
      [[TLFCustomEvent sharedInstance] logAppContext:logicalPageName
      applicationContext:applicationContext referrer:referrer] ;
  5. Configure traffic capture on Passive Capture Application (PCA).

    Data is submitted from the iOS SDK to the PCA by using specific content types. The PCA is typically configured to capture these content types by default. You verify that these content types are enabled for capture through the PCA web console.

    Note: After the completion of the steps in this section, data is processed by IBM Tealeaf.
    1. Verifying PCA capture type configuration. You use the PCA web console to verify that the content types submitted by the iOS SDK are being captured by the PCA. The iOS SDK submits messages by using the application/json content type.
      Note: Depending on the version of the PCA that you installed, the required content types may already be configured for capture. Each IBM Tealeaf iOS SDK can use a different content type for submitting events for capture to IBM Tealeaf. Be sure to review and verify the content type for each deployed client framework.

      1. Log in to the PCA web console.
        <PCAServer>:8080

        where <PCAServer> is the host name of the PCA server.

      2. Click the Pipeline tab.
      3. Click Edit Type Lists.
      4. In the Capture All POST Types box, verify that the following values are included.
        text/json
        text/x-json
        application/json
        application/x-json
      5. Click Add.
      6. The PCA is now configured to capture the required content types. All subsequent hits of this type are captured.
      7. Save your changes.
    2. Optional: Configuring PCA for screen capture from iOS SDK. You can set up the iOS SDK to do a screen capture during the initial load of each view or screen of your web application. These screen captures are forwarded to the IBM Tealeaf Target Page in PNG and JPG format for use during session display. PNG files are not compressed, while JPG is a compressed format. APNG file is approximately 20 KB to 35 KB in size; a JPG file is 6 KB to 15 KB.
      When this option is enabled, you must configure the PCA to capture these screens. By default, the PCA drops capture of binary or static content, so you must configure it to capture images that are submitted as binary POSTs to the target page. For more information, see the “Screen capture at run time” section in Configurable items.

      1. Log in to the PCA web console.
        <PCAServer>:8080

        Where <PCAServer> is the host name of the PCA server.

      2. Click the Pipeline tab.
      3. Click Edit Type Lists.
      4. In the Excluded File Extensions list, verify that png or jpg is listed.
      5. In the Included File Extensions list, verify that png or jpg is not listed.
        Note: If a file extension is included in this list, then all instances that are sent as responses are captured, which greatly expands the volume of data that is captured by the PCA. Capture in this manner is not required.
      6. In the Binary POST Types box, enter the following value.
        image/png
      7. Click Add.
      8. The image/png POST type is added and enabled for capture. This setting allows the PNG posts to be captured by the PCA.
      9. Save your changes.
    3. Enabling decompression of compressed POSTs.
      1. In the PCA Web Console, click the Pipeline tab.
      2. Select Inflate compressed requests and responses.
      3. Save your changes. The compressed POSTs are now automatically decompressed by the and processed normally.
  6. Configure sessionization for iOS applications.

    The iOS SDK uses a tiered approach to generating identifiers for mobile native application sessions. A summary of the approaches for generating identifiers follows.

    • Use TLTSID identifier that is provided by web server.This solution uses the session identifier that is provided by your web server environment, which forces the mobile native application to use identifiers that are consistent with your non-mobile sessions. Ideally, this identifier is provided as a TLTSID value, which is the default session identifier value within Tealeaf.

      Important:
      If possible, use this method of generating the session identifier.

      To enable this method of generating session identifiers, the first hit of your mobile native application session must be forced to be a web hit that touches the server or servers that generate session identifiers.

      Ideally, the session identifier that is generated by your web server is provided by the Tealeaf Cookie Injector, which generates session IDs that are unique within Tealeaf.

      Use another identifier that is provided by web server.
      In some environments, the TLTSID value is not used as the session identifier. In these cases, you must force the first hit to be a web hit targeting the web server, and you must deploy a session agent in your Windows pipeline to map the proper session identifier for Tealeaf.

      Important:
      This method is not validated in a customer environment and is not officially supported. For more information, contact Tealeaf technical support.

      To enable this method of generating session identifiers, the first hit of your mobile native application session must be forced to be a web hit that touches the server or servers that generate session identifiers.

      If you are using a session identifier other than TLTSID, you must include the Sessioning session agent in your pipeline to identify your session identifier for Tealeaf. If you already deployed Tealeaf to capture non-mobile sessions and the session identifier was already defined by your web server, this configuration was probably already completed. Verify that it is present and functioning in the Windows pipeline.

    • Configure the TLTSID by changing the string value of SessionizationCookieName from TLFConfigurableItems.plist. SessionTimeout should be set together with SessionizationCookieName. When the time out happens, iOS SDK auto generates a new Session ID and assigned it to the variable of SessionizationCookieName. This customized session identifier is a hashed value that is submitted as a cookie in the first hit and all subsequent hits.

      To get the generated session ID, implemented the following:

      @protocol TLFLibDelegate <NSObject> 
      @optional /** After set a delegate to your TLFApplication implement this
      callback to generate your custom Session ID */
      - (NSString*)sessionIdGeneration; @end

      If you do not configure SessionizationCookieName, by default, it will use TLTSID, which is generated by Sessioning session agent in your pipeline.

    A note on sessionization for upgraded environments

    If you upgraded your iOS SDK from a version before 8.6.7.3, the method of sessionization changed.

    • Previously, the iOS SDK submitted session identifiers using the X-Tealeaf-Session header.
    • Beginning in iOS 5, the headers are no longer available to the local application.
    • To sessionize, Tealeaf now submits session identifiers as cookies.

    After you upgrade your iOS SDK from a version before 8.6.7.3, you change how sessionization is managed within your native application.

    • If you use the TLTSID value, you do not need the Sessioning session agent to map session identifiers into the request.
    • The Android SDK uses the Sessioning session agent for session identification. Do not remove it if you are also deploying an Android mobile native application.
  7. Configure the framework within the client application during run time.

    As needed, you can change framework settings within the client application during run time. You define these settings during initialization of the application by using the framework API, and update them as needed.

    The following configuration items can be configured dynamically from the client.

    • Dynamic PostMessageURL: Changes the target URL for iOS Logging Framework as needed.
    • KillSwitchURL: Activates the killswitch on the iOS Logging Framework as needed.

    For more information, see the “Dynamic configuration items” section in Configurable items.

Expected outcome

This tutorial describes the basic steps to configure the Tealeaf and Windows based servers to capture and process data that is submitted from the iOS SDK. Complete the tutorial to enable processing of submitted data.

Join The Discussion

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