Listening for Good Moments

Register a background observer to trigger a callback when it’s a good moment to engage the user.

You can register a persistent context observer that evaluates the user’s real-world context in the background and triggers a callback when a good moment is detected. This is useful for scenarios like showing an in-app message or prompt at the right time, without requiring repeated manual checks.

This API is only available in iOS at the moment. Please reach out to our team if you need this API in Android.

Registering an Observer

Use registerContextObserver(flowName:callbackOnFirstGoodMoment:) to begin monitoring for good moments:

ContextManager.registerContextObserver(flowName: "upsell_in_app_message") { context in
    // Present your upsell here and then log its positive/negative outcome
}

Once a good moment is detected:

• The callback is triggered on the main thread.

• The observer is automatically unregistered for that flow name.

Logging Outcomes

There is a key difference in this observer when compared to traditional Capturing Context methods: don't log a skipped outcome anywhere. The shouldUpsell property will always be true when this callback is called, so there's no need to check it, nor log skipped.

Logging positive and negative outcomes (including Alternative Outcomes) should happen as usual. For more details on when and how they should be logged, see Logging Conversions.

Unregistering an Observer

You can cancel an active observer at any time using:

ContextManager.unregisterContextObserver(flowName: "upsell_in_app_message")

This is safe to call multiple times — if no observer is registered, the call has no effect.

Calibration Phase

During the Calibration Phase, This observer also supports collecting data during the calibration phase.

Best Practices & Caveats

• One observer per flow: registering another observer with the same flow name replaces the previous one.

• Multiple flows are independent: using different flow names will create multiple independent observers. These observers are not triggered simultaneously, helping you avoid overlapping user prompts.

• Callback is called only once: if you want to listen again after a good moment was found, re-register the observer.

FAQs

Why does the observer unregisters itself after identifying the first good moment?

Due to the ongoing evaluation of the context, the user’s context is unlikely to have changed significantly. Without a built-in safeguard, multiple callbacks in quick succession could result in repeated in-app messages, leading to potential UX issues.

Rather than requiring each developer to implement their own cooldown logic (for example, limiting messages to once per hour), the SDK takes a conservative approach: it removes the observer after the first callback. If your app needs to continue listening for updates, you can re-register the observer as needed.

This approach reduces the risk of flooding users with repeated upsell screens or modals, especially in production environments where missing cooldown logic may go unnoticed during testing.

How does model training work during the calibration phase?

During the calibration phase, prompts are shown at random times, similar to how the control group operates after calibration.

For example, if the agreed Prompt Intensity is 1%, the system evaluates context continuously but displays a prompt at random only 1% of the time. These randomly triggered prompts and their outcomes are then used to train the model.

Once the initial model is deployed, the audience is split:

• The control group continues to see prompts with a 1% random chance.

• The ContextSDK group sees prompts based on the top 1% of context-optimized moments, as determined by the trained model.

This approach ensures the model is trained on unbiased data while maintaining a consistent baseline for comparison.