Continuing mobile sessions in WebViews

For mobile applications that contain user journeys that extend to WebViews, you may want to track the mobile application and web behaviors in a unified session. Starting in version 0.3.0 of Heap Core for iOS and Android, user and session IDs, as well as identity, can be passed from the mobile SDKs to Heap.js running in a WebView to track the complete user journey of your mobile application users.

Before you begin

📘

WebView support is only available for native Android and iOS apps at this time.

First, make sure your mobile application uses version 0.3.0 or higher of the Heap Core SDK for your target platform. For information about the latest versions of Heap Core, check the changelogs for the iOS and Android SDKs.

• On iOS, check your Podfile or Swift Package Manager for HeapSwiftCore and ensure the version is 0.3.0 or higher.
• On Android, check for the following dependency and ensure it's targeting version 0.3.0 or higher.
  • If using Android Core 0.5.0 or higher, be sure to include the WebView integration artifact as well.

dependencies {
  // Check the changelog for the latest version of Heap Core.
  implementation 'io.heap.core:heap-android-core:0.7.2'

  // Required starting in Android Core 0.5.0
  implementation 'io.heap.core.web:webview-heapjs:0.7.2'
}

dependencies {
  // Check the changelog for the latest version of Heap Core.
  implementation("io.heap.core:heap-android-core:0.7.2")

  // Required starting in Android Core 0.5.0 (Same version as Core artifact)
  implementation("io.heap.core.web:webview-heapjs:0.7.2")
}

Configuring your application

Before data is loaded into your WebView, you must first start recording and attach Heap to your WebView.

Starting recording

Recording can be started using the startRecording method shown in the quick start guide for your chosen platform.

📘

You'll want to make sure that the app ID used to start recording in your mobile application is the same app ID used in your Heap.js installation. This integration will not work if the mobile application and web installations use different app IDs.

Heap.shared.startRecording("YOUR_APP_ID")

Heap.startRecording("YOUR_APP_ID")

Attaching Heap to your WebViews

To attach Heap to your WebView, you'll need to call attachWebView. This Heap API method takes in the WebView Heap is being attached to, a list of domains with which the integration should work, and a HeapJsSettings object. The HeapJsSettings object specifies:

• The domain to be used with the cookie (either an exact domain, or . prefixed).
• The cookie path (defaults to /).
• Boolean to denote whether to use secure cookie.

📘

WebViews on iOS and Android are not guaranteed to be always isolated or always in sync with each other. For this reason, we recommend that if you attach Heap to one WebView in your application, you attach Heap to all WebViews in the application.

Below is an example for setting a cookie for https://app.example.com without using an explicit domain and using the default cookie path.

// Assuming some WKWebView named `webView`

// Attach Heap to the WKWebView.
Heap.shared.attachWebView(
  webView,
  origins: ["https://app.example.com"],
  bindHeapJsWith: .init(domain: ".example.com", path: "/", secure: true)
)

// Load the page in the WKWebView only *after* recording has started and Heap has been attached.
webView.load(URLRequest(url: "https://app.example.com"))

// Assuming some WebView named `webView`

// Ensure JavaScript is enabled for the WebView.
webView.settings.javaScriptEnabled = true
// Ensure cookies are enabled. This is true by default.
CookieManager.getInstance().setAcceptCookie(true)

// Attach Heap to the WebView.
Heap.attachWebView(
    webView,
    setOf("https://app.example.com"),
    HeapJsSettings(".example.com", path = "/", isSecure = true)
)

// Load the page in the WebView only *after* recording has started and Heap has been attached.
webView.loadUrl("https://app.example.com")

Removing Heap from your WebViews

If you've determined that you no longer want to sync web and mobile application users and sessions, you'll want to remove the Heap.js cookie that was set by the integration. As when setting the cookie, because WebViews are never guaranteed to be isolated or in sync, you'll want to remove the cookie from all WebView instances in your application.

Due to differences in Android and iOS WebView architectures, there are slightly different methods for removing Heap from your WebViews for each platform.

Removing from iOS WKWebView

To remove the integration cookie on iOS, call removeHeapJsCookie and give it the app ID and the instance of the WKWebView. This should remove the cookie during the current run of the application.

// Assuming some WKWebView named `webView`

Heap.shared.removeHeapJsCookie(for: "YOUR_APP_ID", from: webView)

Removing from Android WebView

Due to constraints in the Android WebView system, once a single WebView is bound, all WebViews in the application are bound while the application is running. Even calling stopRecording will not stop the WebView session from being bound. The only way to unbind Heap from a WebView on Android is to call removeHeapJsCookie and restart the application.

// Assuming some WebView named `webView`

// Creating the HeapJsSettings object
val hjsSettings = HeapJsSettings(".example.com", isSecure = true, path = "/")

// Attach Heap to the WebView
Heap.attachWebView(webView, setOf("https://app.example.com"), hjsSettings)

// To unbind, call the remove method with the same HeapJsSettings from attachWebView
Heap.removeHeapJsCookie("YOUR_APP_ID", hjsSettings)

// Remember, an application restart is necessary for this to take effect.

Limitations

Due to a known limitation in Android, this integration does not work with Chrome Custom Tabs.