Skip to content

Context Insights

This page explains how to use ContextSDK to get insights into how your app is being used in the real world for Context Insights.

Overview

  • Step 1: Add ContextSDK to your app
  • Step 2: (Optional) Log any events
  • Step 3: Ship an App Store update with ContextSDK

Impact on your app

Less than 0.2% CPU Usage

0.6 MB Memory Usage

Adds less than 700kb to your app's binary size

No PII processed or stored

Installation

Add the following dependency to your Podfile and run pod install 

pod 'ContextSDK'

  1. Download the latest release: https://storage.googleapis.com/de73e410-context-sdk-releases/latest/ContextSDK.zip
  2. Drag & Drop the ContextSDK.xcframework folder into the Xcode file list
  3. Go to your project settings, scroll down to Frameworks, Libraries, and Embedded Content, add ContextSDK.xcframework, and select Embed & Sign

If you want to download a specific version, you can replace latest with the desired version number, e.g. https://storage.googleapis.com/de73e410-context-sdk-releases/3.1.0/ContextSDK.zip

Add https://github.com/context-sdk/context-sdk-releases as dependency.

Head over to the Unity plugin page for instructions on how to use Context Insights for your Unity game.

After you installed ContextSDK, you need to add your license key and provide a way to send information to us. In your willFinishLaunchingWithOptions: (or anywhere before you access the SDK) setup the ContextManager:

AppDelegate.swift
import ContextSDK
AppDelegate.swift willFinishLaunchingWithOptions:
ContextManager.setup("YOUR_LICENSE_KEY")

Optional: Track additional Events

Optionally, you can log specific events to get a better understanding of how the real world context influences your app.

Use this to track users navigating through different screen in your app. It allow us to provide you insights into which screen is most commonly used in which real world context.

ContextManager.trackPageView("page_identifier")

Use this to track certain user actions, like when a user enabled a certain feature, when a user tapped a button, when the user created an account, or when the user shared something. This allows us to provide you insights into which user actions are most commonly done in which real world context.

ContextManager.trackUserAction("user_tapped_share_button")

Use this to track certain events in your app. This can be used generically to track any type of event. For example, you can add this to your existing analytics code to log all your existing events into ContextSDK. This allows us to provide you insights into which events are most commonly triggered in which real world context.

ContextManager.trackEvent("custom_event")

Logging the outcome of sales events (e.g. in-app purchases, orders, etc.) allows us to provide you with detailed insights in which real world context has a positive or negative effect on your app's conversion rates.

The integration is slightly more complex, as you need to track the context before before you show the prompt, and then log the outcome after the user has made a decision. For example, when users purchase your upgrade through FaceID, most likely they've stopped e.g. walking, therefore influencing the context.

In most cases, ContextSDK will execute your block instantly. Only if your app was recently launched, or resumed from the background, it will take up to a few seconds to get a full context.

ContextManager.optimize("upsell") { context in
  // [Show the upgrade prompt here right after fetching the context]
  // Once you know if the user purchased or dismissed the upsell, log the outcome:
  context.log(.positive) // or .negative
}

It's critical you trigger your prompt inside the block, which behaves as follows:

  • The callback is instantly executed if your app has been running for at least 3 seconds
  • The callback being executed within 3 seconds if your app was just put into the foreground recently

Forcing instant callbacks when tracking conversions

There are cases where you may prefer to always instantly have your callback executed. For example, when you want to show a prompt right after a certain user-action, to prevent the prompt showing up when the user already left the screen. For those cases, you'd need to use the ContextManager.calibrate method with the maxDelay: 0 parameter:

ContextManager.calibrate("upsell", maxDelay: 0) { context in
  // [Show the upgrade prompt here right after fetching the context]
  // Once you know if the user purchased or dismissed the upsell, log the outcome:
  context.log(.positive) // or .negative
}

Using maxDelay: 0 means that the context object may not be fully ready, which will reduce data quality. We recommend not using this approach right after the app start, but only in places where the app usually has already been running for a few seconds.

Optional: Provide Custom Signals

Custom signals are like custom parameters you'd pass into your analytics service. They are used to provide you additional insights.

Global signals are used for all Context Insights events. We recommend using this to set AB test information, generic login or account information, or any other information that is relevant across all event types.

ContextManager.setGlobalCustomSignal(id: "ab_test", value: AbTestManager.currentTestName())
ContextManager.setGlobalCustomSignal(id: "user_has_premium_subscription", value: true)

Note that as per our privacy policy and license agreement, it is your responsibility to not pass any PII into ContextSDK.

You can also pass in custom signals for just a specific Context Insights event.

let customSignals: [CustomSignal] = [
  CustomSignalFloat(id: "percentage_onboarding_finished", value: 0.3),
  CustomSignalString(id: "upsell_copy_button_used", value: "Purchase Premium"),
]

ContextManager.trackPageView("login_page", customSignals: customSignals)

Note that as per our privacy policy and license agreement, it is your responsibility to not pass any PII into ContextSDK.

Go Live

Now all that's left is to ship your update to the App Store to start gaining context insights. Continue to the release page for a final check before shipping, as well as other deployment tips.