Listening for Good Moments
Register a background observer to trigger a callback when it’s a good moment to engage the user.
Last updated
Was this helpful?
Register a background observer to trigger a callback when it’s a good moment to engage the user.
Last updated
Was this helpful?
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.
Use registerContextObserver(flowName:callbackOnFirstGoodMoment:)
to begin monitoring for good moments:
Once a good moment is detected:
The callback is triggered on the main thread.
The observer is automatically unregistered for that flow name.
There is a key difference in this observer when compared to traditional 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.
You can cancel an active observer at any time using:
This is safe to call multiple times — if no observer is registered, the call has no effect.
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.
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.
During the calibration phase, prompts are shown at random times, similar to how the control group operates after calibration.
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.
During the , This observer also supports collecting data during the calibration phase.
For example, if the agreed 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.