ContextSDK Guide

Webhook-based delivery status: The primary visibility mechanism is the delivery status webhook. ContextSDK posts a callback each time a message changes state. The webhook payload includes:

• delivery_status - current state of the message (e.g., pending, shown, opened, fallback, fallback_delivered, fallback_opened, cancelled, unable_to_deliver, failed)
• delivery_method - whether delivery was context-aware or fallback
• planned_delivery_method - what method was intended at scheduling time
• timestamp - when the status change occurred
• seconds_since_delivery - time elapsed since delivery (for open events)
• campaign_id, idempotency_key, user_id - for correlation

Device classification callbacks: Separate DEVICE_TRANSITION webhook events are emitted when a device's BOT eligibility classification changes, reporting both the previous and new status (eligible, ineligible, unknown). This allows you to track the proportion of your user base that is BOT-eligible over time.

Dashboard: Aggregate delivery metrics and campaign performance are available in the ContextSDK dashboard.

What is not exposed: Internal model decisions (e.g., moment scores, hold durations, suppression reasons) and model version metadata are not currently surfaced externally. We are open to working closely on structured A/B test reporting - comparing delivery outcomes across model variants.

API error responses: The REST API returns structured error responses for invalid requests, making it straightforward to diagnose integration issues during QA (e.g., missing required fields, invalid delivery window configuration, unknown device tokens).

In addition to those tools available externally we internally have full audit logging across all messages being sent and are happy to share data where relevant upon request.

We size capacity based on devices and messages per day rather than requests per minute, as that is a more meaningful unit for campaign-style workloads.

Our infrastructure is built to scale horizontally and handles variable traffic via auto-scaling. To date, the system has operated comfortably at volumes in the range of several million active devices and several million notifications per day.

To ensure your integration is sized appropriately, please share the expected number of active devices and the anticipated daily message volume. We will validate current capacity headroom against your numbers and provision additional baseline capacity if needed prior to launch. Auto-scaling handles burst traffic beyond the provisioned baseline.

In addition, we recommend scheduling notifications with a short jittering delay. This ensures that large volumes are not sent all at once, but instead distributed more evenly over a defined period of time.

The behaviour differs by device classification:

Eligible devices (RELIABLE): The system continuously monitors context and attempts context-aware delivery (via silent push and background tasks) throughout the entire delivery window. If the window expires without a confirmed delivery, a traditional push notification is sent as a final fallback at the end of the window.

Ineligible (UNRELIABLE) and Unknown devices: These devices follow the fallback path, governed by the optional fallback_delivery_time parameter:

• fallback_delivery_time is defined: The device continues to receive silent push attempts until that time is reached, at which point a traditional push notification is sent. This allows even lower-confidence devices to benefit from context-awareness within a bounded window.
• fallback_delivery_time is not defined: A traditional push notification is sent immediately at the start of the delivery window (i.e., at ingestion time or at delivery_window_start_time).

We recommend always setting a fallback_delivery_time! A good default is the same time you would ordinarily send a standard push notification.

The integration touches three areas:

• Mobile (Engineering - App Release Required): An app update is required to integrate the ContextSDK on iOS. The SDK handles background context collection and communicates with the ContextSDK backend. Integration instructions are available in our documentation. There is currently no Android support. Link: https://docs.contextsdk.com/context-push/integration
• Backend / CRM (Braze Configuration): Braze must be configured to route messages through the ContextSDK REST API instead of delivering directly. This includes passing the required delivery window parameters (target_delivery_time or deliver_within_hours, and optionally delivery_window_start_time and fallback_delivery_time) with each scheduled message. Link: https://docs.contextsdk.com/context-push/push-notification-providers/simple-web-request
• Analytics (Webhook Endpoint): A webhook endpoint can be configured to receive delivery status callbacks from ContextSDK. These callbacks report on message and device-level events - including whether a notification was sent via context-aware delivery or fallback, whether it was opened and the device's BOT eligibility classification. This data can be ingested into your analytics stack or fed back into Braze for campaign attribution.
• Device Classification: Devices are classified as eligible (BOT-capable), ineligible or unknown. Understanding this classification is important for evaluating performance, as eligible and ineligible devices follow different delivery paths and will show different delivery patterns.

Braze initiates the process. When a campaign is ready to send, Braze posts the messages to the ContextSDK system via REST (HTTP). From that point, ContextSDK takes ownership of delivery timing.

A delivery window must be defined for each message. This can be expressed in two ways:

• Relative: e.g., deliver_within_hours: 5 - a 5-hour window starting from the time of posting (or from an optional delivery_window_start_time if scheduling ahead).
• Absolute: e.g., target_delivery_time: "2026-04-01T19:00:00Z" - a hard deadline by which delivery must occur.

The minimum window duration is 2 hours. Windows can be scheduled up to 7 days in advance using delivery_window_start_time.

Once a message is ingested, ContextSDK monitors device context and delivers at the most suitable moment within the window. Braze is not involved in the timing decision after ingestion!

For delivery status reporting, a webhook endpoint can be configured on the customer side. ContextSDK will post status updates whenever a message changes state (e.g., sent, shown, opened). This keeps reporting in sync.

Important: We also recommend defining a fallback_delivery_time - this serves as a safety net for devices that are ineligible or have insufficient context data, and should closely align with the timing Braze would normally use for standard push delivery. This way we provide an uplift without regressing performance of ineligible devices by bad timings.

You get clear visibility into what happened:

• When a message was sent
• Whether it was context-aware or fallback
• If and when it was opened

This can be tracked via webhooks and in our dashboard. For deeper analysis, we also support structured A/B testing.

Yes. Our system is built to scale and already handles millions of devices and notifications per day. We automatically adjust capacity and recommend spreading large campaigns slightly over time to ensure smooth delivery.

Context-aware delivery depends on background capabilities on iOS.

• Eligible devices - receive fully optimized timing
• Other devices - fall back to standard push delivery

So performance only improves - it never gets worse.

We always make sure the message gets delivered. If no ideal moment is found within the time window, the push is sent at the end of the window (or at your defined fallback time). This ensures you get the upside of better timing - without risking missed messages.

There are three parts:

• App (iOS): You need to integrate the ContextSDK and release an app update
• Push provider: Messages are routed through ContextSDK instead of being sent directly
• Analytics: You can optionally set up a webhook to track delivery and performance

No major backend rebuild is needed.

Your push provider still triggers the message. Once the message is sent to ContextSDK, we take over and decide when it should actually be delivered. You define a time window (for example: within the next 5 hours), and ContextSDK finds the best moment within that window based on the user's real-world context.

In-App Placements: In-app placements are specific moments or spaces within your app where prompts for upgrades, ads or premium features are displayed. These placements are carefully chosen opportunities to engage users and drive conversions, such as subscription sign-ups, in-app purchases or ad views.

Why is one in-app placement not always enough? The math is simple: More opportunities = higher probability of conversions.

The Current Problem: ContextSDK's optimized timing means prompts are shown less frequently than the app's previous "always-on" logic. While this improves user satisfaction, it also reduces the overall number of impressions, impacting sales potential.

The Solution: By adding a second placement with ContextSDK logic, you double the chances to engage users. Two chances at the right moments outperform countless poorly timed prompts.

We offer dedicated support throughout integration and beyond, including:

• Technical guidance for smooth implementation
• Strategy consulting to optimize engagement workflows
• Performance monitoring to fine-tune results

Yes. We recommend running an A/B test to compare context-driven engagement with your current setup. Our team will help set up experiments to provide clear performance insights.

Apps using ContextDecision have seen conversion boosts of up to 81% with fewer prompts, leading to:

• Higher revenue per user (ARPU)
• Better lifetime value (LTV)
• Reduced churn from unnecessary engagement

Yes. ContextDecision is built with privacy in mind:

• On-device processing - No data leaves the user's phone.
• No personal data collected - We only track engagement signals.
• GDPR & CCPA compliant - Fully aligned with global privacy standards.
• SOC 2 certified - Meeting high security and privacy standards.

We provide controlled experiments to measure impact on conversions, retention and revenue. A dedicated dashboard is in development to track results in real time.

No. Your app's design and user experience remain unchanged. ContextDecision works in the background, making engagement smarter while you retain full control over how offers appear.

Integration is simple - just a few API calls. ContextDecision works seamlessly with your existing:

• Push providers (Braze, OneSignal, RevenueCat, etc.)
• Customer engagement platforms

No! ContextDecision starts working immediately but improves over time:

• Dashboard Insights - Needs at least 10,000 logged events for optimal analytics.
• AI Model Training - Needs 1,000 conversion events for custom model optimization.

For best results, apps with 100,000+ monthly active users generate meaningful engagement patterns quickly.

ContextDecision is ideal for any app looking to improve engagement and monetization, including:

• Gaming - Showing in-app purchase prompts at the right time.
• Health & Fitness - Encouraging users to complete workouts.
• Education - Surfacing learning content when users are focused.
• Social & Dating Apps - Re-engaging users when they're in the right mindset.
• Finance & Subscriptions - Nudging users at key decision points.

ContextDecision ensures offers don't interrupt users at the wrong time, such as when they are walking, commuting or in a hurry. By increasing offer frequency only at the best moments, apps experience:

• Higher conversion rates - Users see offers when they are most likely to convert.
• Less user fatigue - Avoid overwhelming users with untimely prompts.
• Better retention - A smoother, more natural user experience.

Our on-device AI models process non-personal signals like:

• Device Usage - Screen on/off, app activity, battery level
• User Motion - Stationary, walking, running, commuting
• Environmental Factors - Time of day, ambient light, screen brightness
• Interaction Trends - Unlock patterns, scrolling behavior, in-app session depth

Traditional engagement tools rely on fixed schedules or simple behavioral rules, often leading to poorly timed prompts and user frustration. ContextDecision adapts in real-time, detecting when a user is actively engaged and ready to convert - leading to higher engagement and better retention.

ContextDecision is an AI-powered decision engine that helps apps determine the best moment to show in-app offers, paywalls or engagement prompts. It analyzes over 300 real-world signals directly on a user's device - such as motion patterns, device activity and time of day - to ensure offers appear only when users are most receptive.

ContextPush requires users to accept the standard push notification permission request in order to send notifications. Beyond that, no additional permissions are needed, as we work with data that is already available to your app.

ContextSDK integrates seamlessly with your existing push provider, customer engagement platform or custom-built server logic. ContextPush doesn't operate standalone - it works in harmony with the logic you've already set up. Just let us know which one you're using!

ContextPush uses the accelerometer, gyroscope and other on-device signals from your users' smartphones to predict their current context - whether they're walking, sitting or commuting. Based on this data, we time your non-transactional notifications to be sent at the perfect moment, increasing engagement. All of this is done without processing any PII (Personally Identifiable Information).

ContextPush only has a minimal impact on your app. Adding less than 700kb to your apps footprint and consuming less than 1MB of RAM.

ContextSDK optimizes only non-transactional messages, such as promotions, reminders or engagement campaigns. These are timed perfectly based on your users' real-world context. Transactional messages - like order confirmations or password resets - that need to be sent immediately are unaffected and will continue to be delivered in real-time.

Our models continuously learn and improve based on real-world interactions, ensuring they stay optimized for engagement and conversions. Plus, ContextSDK supports over-the-air (OTA) updates, meaning improvements and new features roll out seamlessly - no manual app updates required.

Yes! We recommend running an A/B test to compare ContextSDK's impact on engagement and conversions against your current setup. Our flexible integration allows for easy experimentation before full rollout.

Yes! Poorly timed engagement often leads to user frustration and churn. By delivering messages at the right time, ContextSDK helps reduce spammy interactions and enhances user retention.

Nope! Our on-device AI is optimized for efficiency. Since all processing happens locally, ContextSDK has minimal impact on battery life compared to cloud-based alternatives.

Yes! Since our AI models run entirely on-device, ContextSDK continues to function even when users are offline. No need to rely on cloud-based decision-making - everything happens in real-time on the user's device.

ContextSDK processes over 300 real-world signals, all analyzed directly on the user's device to maintain strict privacy standards. These signals include:

• Device usage: Screen time, app activity and battery status.
• Activity level: Whether a user is stationary, walking or engaging in active movement.
• Environmental context: Time of day, ambient light and device orientation.
• Motion patterns: Signals from gyroscopes and accelerometers to detect movement trends.

These insights are used by our machine learning models to determine the most relevant timing for notifications, paywalls or offers - maximizing engagement without user fatigue.

Our customers typically see significant lifts in engagement and conversions, leading to improved ARPU and LTV. Specific ROI metrics depend on your app and user base, but we've helped apps achieve results like an 81% conversion boost with fewer prompts.

Yes! ContextSDK is designed to integrate seamlessly with your existing push notification providers, analytics tools and backend systems. This ensures smooth implementation with minimal disruption to your current workflows.

Our team provides full support during integration and beyond. Whether it's technical guidance, training or customization, we're here to ensure ContextSDK delivers maximum value for your app.

To get started, ContextSDK requires the following:

• Insights for the Dashboard: A minimum of 10,000 logged events is needed for the dashboard to generate actionable insights. For larger apps, this can take a day, while smaller apps may need longer.
• Custom Model Training for Decision: At least 1,000 positive conversion events are required to train a tailored machine learning model for precise decision-making. We typically work with apps that have 100,000+ monthly active users to ensure faster model adaptation and impactful results.

Not at all. ContextSDK integrates seamlessly into your existing workflows, requiring just a few API calls to enable smarter, context-aware prompts. You'll retain full control over your app's design and user experience.

We conduct controlled experiments with your app to measure the impact of context-driven engagement on key metrics like conversions, retention and user satisfaction. A dedicated dashboard to track your results and insights is currently in development and will soon be available for seamless performance monitoring.

ContextSDK is ideal for any app looking to boost engagement, retention and revenue. Popular industries include:

• Gaming: Timing in-app purchases and rewards perfectly.
• Health & Fitness: Encouraging habit formation and daily engagement.
• Education: Delivering content when users are most focused.
• Entertainment & Social Media: Enhancing content consumption and ad effectiveness.
• Finance: Sending relevant nudges for transactions or financial goals.

If you have unique use cases, our flexible platform can adapt to your app's specific needs.

Integration is simple and quick. ContextSDK is designed to work seamlessly with your existing push providers and analytics tools. Most apps can complete integration in just a few days, with minimal impact on codebase and resources.

ContextSDK takes privacy seriously and is built with a privacy-first approach:

• On-Device Processing: All data processing happens locally on the user's device, ensuring that no Personally Identifiable Information (PII) is stored, transferred or shared.
• Privacy Compliance: Our technology adheres to global privacy standards, including GDPR, CCPA and other key regulations.
• SOC 2 Certification: ContextSDK is SOC 2 certified, which means our platform meets stringent security, availability and confidentiality requirements. This certification demonstrates our commitment to maintaining the highest standards of data security and privacy.

Unlike traditional tools that rely on rigid rules or time-based triggers, ContextSDK uses machine learning and real-world signals (like activity or device usage) to adapt dynamically to user behavior. This ensures your prompts are sent at the optimal moment, maximizing engagement and reducing user fatigue.

Wizz saw an 81% conversion lift. Blackbox saw 50% revenue uplift. Results depend on your app, baseline and how many placements you test - we help you measure this properly from day one.

Yes. Any in-app prompt can benefit from better timing - upsells, feature introductions, onboarding steps, rewarded ad placements or subscription upgrade nudges.

No. It uses motion and sensor signals only - no GPS, no location tracking.

About a day. A few lines of code, no new permissions, no UI changes required.

Yes. ContextDecision sits alongside your existing paywall infrastructure, deciding when to trigger the show. It doesn't replace your tools - it tells them when to act.

It analyzes real-world signals on the device - motion, activity, device state - to determine whether the user is in a high-receptivity moment. Paywalls are shown when users are most likely to engage and suppressed when they're not.

Yes. Poorly timed notifications are one of the main drivers of opt-outs. By sending only when users are receptive, ContextPush reduces notification fatigue and helps retain permission.

No. ContextPush uses only sensor data already available to any iOS app. No location permission is needed.

Results vary by app and audience. We recommend running an A/B test to measure impact against your current baseline - our team helps set this up.

Yes. It integrates with Braze, OneSignal, Customer.io and any custom server logic. Your existing setup stays in place - ContextPush just adds smarter delivery timing on top.

Rather than sending at a fixed time, ContextPush holds the notification until the user is in a receptive real-world state - not commuting, not walking, not distracted. Better timing means better open rates.

Yes. GDPR and CCPA compliant and SOC 2 Type 2 certified.

Under 700KB added to your app footprint, with under 1MB RAM usage.

The ML model runs locally, analyzing sensor signals in real time and returning a context state in under 2 seconds - no network call required.

Entirely on-device. No data leaves the user's phone.

Raw sensor data from the accelerometer, gyroscope and other built-in iPhone sensors - translated into meaningful context states like commuting, walking, stationary, or relaxing at home.

Most integrations are live within a day. Just a few lines of code, no new app permissions required.

iOS. Android support is on the roadmap.

Analytics tools report on what users have done. ContextSDK detects what users are doing right now - their physical context in the real world - so apps can act in the moment, not after the fact.

No. All processing happens on-device. No PII is ever collected, stored or transmitted. ContextSDK is GDPR compliant and SOC 2 Type 2 certified.

Accelerometer, gyroscope, device activity, screen state, ambient signals and motion patterns - over 300 signals in total, all processed locally on the device.

ContextSDK is an on-device context intelligence platform for mobile apps. It processes real-world device signals - motion, activity, device state - through on-device ML models to help apps act on what users are actually doing, not just who they are.

No. ContextSDK sits alongside your existing stack - adding a context layer so your current tools know when to act, not just what to show.

Most guides focus on paywall design and pricing structure. This one also covers timing - specifically, how real-world user context affects conversion in ways that in-app analytics alone can't detect.

No. It's a practitioner guide built around real industry data and contributions from monetization experts across the ecosystem.

Yes, completely.

Product managers, growth leads and monetization teams at mobile apps. No coding required to get value from it.

A practical framework for modern app monetization - covering models, tech stack, data fundamentals, funnel optimization and the real-world moments that drive subscription conversion.