The Acoustic Analytics Developer Hub

Welcome to the Acoustic Analytics developer hub. You'll find comprehensive guides and documentation to help you start working with Acoustic Analytics as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

iOS: Server configuration

Quick start server configuration

Overview

Skill Level: Any
Capture and process data that is submitted from the iOS SDK
This tutorial describes the basic steps to configure the Experience Analytics (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 Experience Analytics (Tealeaf) SDK for iOS by following these instructions:

Step-by-step

1. Configure data privacy.

Acoustic Experience Analytics (Tealeaf) provides mechanisms for masking or blocking sensitive customer information, such as credit card numbers, from being transmitted and captured by Acoustic Experience Analytics (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 Acoustic Experience Analytics (Tealeaf).

Note:

Due to the way in which client framework data is submitted to Acoustic Experience Analytics (Tealeaf) for capture, to mask or block sensitive data you apply filtering through the capturing client framework. While other Acoustic Experience Analytics (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.

Acoustic Experience Analytics (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, Acoustic Experience Analytics (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 Acoustic Experience Analytics (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 Acoustic Experience Analytics (Tealeaf) iOS SDK can use a different content type for submitting events for capture to Acoustic Experience Analytics (Tealeaf). Be sure to review and verify the content type for each deployed client framework.

a. Log in to the PCA web console. <PCAServer>:8080 where <PCAServer> is the host name of the PCA server.

b. Click the Pipeline tab.

c. Click Edit Type Lists .

d. In the Capture All POST Types box, verify that the following values are included.

text/json

text/x-json

application/json

application/x-json

e. Click Add .

f. The PCA is now configured to capture the required content types. All subsequent hits of this type are captured.

g. Save your changes.

  1. 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 Acoustic Experience Analytics (Tealeaf) Target Page in PNG and JPG format for use during session display. PNG files are not compressed, while JPG is a compressed format. A PNG 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.

    a. Log in to the PCA web console. <PCAServer>:8080 Where <PCAServer>is the host name of the PCA server.

    b. Click the Pipeline tab.

    c. Click Edit Type Lists .

    d. In the Excluded File Extensions list, verify that png or jpg is listed.

    e. 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.

f. In the Binary POST Types box, enter the following value.
image/png

g. Click Add.

h. The image/png POST type is added and enabled for capture. This setting allows the PNG posts to be captured by the PCA.

i. Save your changes.

  1. Enabling decompression of compressed POSTs.

    a. In the PCA Web Console, click the Pipeline tab.

    b. Select Inflate compressed requests and responses.

    c. 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 Experience Analytics (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 Experience Analytics (Tealeaf) Cookie Injector, which generates session IDs that are unique within Experience Analytics (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 Experience Analytics (Tealeaf).

Important:

This method is not validated in a customer environment and is not officially supported. For more information, contact Experience Analytics (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 Experience Analytics (Tealeaf). If you already deployedExperience Analytics (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.

About 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, Experience Analytics (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.

Expected outcome

This tutorial describes the basic steps to configure the Experience Analytics (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.

Updated 9 days ago


iOS: Server configuration


Quick start server configuration

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.