Apple Retention Messaging

In the Retention Messaging section within Integrations, you can configure Apple's Retention Messaging API for subscribers who intend to cancel.

What the API does

Apple's Retention Messaging API lets you choose which message appears on the App Store's cancellation confirmation screen after a customer taps Cancel Subscription. You can use it to remind subscribers what they keep with their plan, reinforce product value, or present an alternate product or offer that may reduce churn.

Apple supports text-only messages, messages with images, switch-plan messages, and promotional offers. In Superwall, you use this integration to set up the callback URL Apple calls, create retention messages in your Message library, and choose which subscribers see them with retention campaigns.

Examples of retention messaging in the cancellation flow:

Apple Callback URL

The dashboard generates a callback URL using your app's public API key:

https://retention-messaging-api.superwall.com/v1/message/<public-api-key>

Superwall registers this URL with Apple for you. You use the same URL for Apple's sandbox and production environments. Apple requires you to register it for sandbox first and pass a performance test there before you turn it on for production.

After the prerequisites, the Retention messaging page walks you through these steps:

1. Get access from Apple: copy the Callback URL, click Request access from Apple and include the URL in your request. After Apple approves your app, click Check access.
2. Set sandbox URL: point Apple's sandbox traffic at the callback URL.
3. Find sandbox subscription: start a sandbox subscription in your app, then click Find active sandbox subscription. Apple's performance test needs an active sandbox subscription.
4. Run performance test: start Apple's sandbox performance test. Results can take a while.
5. Set production URL: turn on the production callback after the sandbox performance test passes.
6. Create sandbox test message: create a starter message to test the flow in sandbox.

The callback URL doesn't change when you switch between Production and Sandbox in the dashboard. The environment selector applies to messages, campaigns and reporting.

Messages

The Message library holds the messages Apple reviews and approves. You then use them in a retention campaign to show them to subscribers.

Create a message

1. Under Message library, click Create message.
2. Enter a Reference name. It's only shown in Superwall.
3. Under Localized variants, enter a Locale, Header and Body for each language. Click Add locale to add more. The first row is the Default. To add many locales at once, click Import and choose a CSV or TSV file with locale, header and body columns.
4. Click Create and submit. Superwall creates the message and submits it to Apple for review.

Headers can be up to 50 characters and bodies up to 144. Messages belong to the environment selected at the top of the page.

A locale can be exact, such as en-US, or a whole language, such as en. A campaign uses the exact locale if the message has it, otherwise the language. Every locale a campaign covers needs a matching variant. The Default variant isn't used as a fallback in campaigns.

Message status

The Status column shows Apple's review state: Not submitted, Submitting, Failed, Pending, Approved, Rejected or Unknown. A message with several locales shows the status of its least-approved locale. If a submission fails, choose Submit to Apple from the message's menu to try again.

Only messages Apple has approved can be shown to subscribers.

Edit a message

Choose Edit from the message's menu to rename it, add locales, remove locales or set the Default locale. You can't change the header or body of a locale after it's created. To change the text, create a new message. If a retention campaign uses the message, you can't edit or delete it.

Preview a message

After a message exists, open the three-dot menu in the messages table and choose the preview action to see a live preview. The preview shows the message payload beside an example cancellation screen, so you can check the header, body, locale, image, and alt text before using the message in a retention campaign.

Default Messages

Use Default Messages to define fallback message mappings by product and locale.

Use a default mapping when you want Apple to show a specific message whenever there is no matching real-time configuration for that product.

Create a default mapping

To create a default mapping:

1. Choose the environment.
2. Select one or more products.
3. Enter the locale.
4. Choose a message. The picker only shows messages for the same environment and locale.
5. Save the mapping.

The dashboard lets you create mappings for multiple products in one action.

Real-time Configurations

Use Real-time Configurations to map product and locale combinations to the retention message behavior Apple should use at runtime.

Supported configuration types

Two real-time configuration types are supported:

• Message: Apple uses the linked retention message.
• Alternate Product: Apple uses the linked message together with an alternate product.

Create a real-time configuration

To create a configuration:

1. Enter a name.
2. Choose the environment.
3. Select one or more products.
4. Enter the locale.
5. Choose the type.
6. If the type is Alternate Product, choose the alternate product.
7. Choose a message. The picker only shows messages for the same environment and locale.
8. Create the configuration.

The dashboard lets you create configurations for multiple products in one action.

If a real-time configuration exists for a product, Apple uses that behavior instead of the default message mapping. When no real-time configuration applies, Apple falls back to the default message.

Reporting

Superwall reports on the retention messages it serves. Reporting appears in two places: overview cards on this page, and two charts in Charts.

Overview cards

Once an app has retention messaging set up, two cards appear at the top of the Retention Messaging page:

• Save Rate: the percentage of retention messages sent where the subscriber did not cancel within 24 hours.
• Total Saves: the number of those subscribers.

Each card draws a sparkline for the selected period and compares it against the previous period of the same length. Selecting a card opens the matching chart with the same environment and date range applied.

Both cards follow the environment and date range selectors in the page header. The date range defaults to the last 30 days. The comparison is hidden when the previous period had no sends, since there is nothing to compare against.

The cards appear once the app has at least one message, message group, or real-time configuration. Apps that have only configured the callback URL do not see them.

With retention campaigns, the Retention campaigns list below the cards shows each campaign's save rate and saves for the same date range.

Charts

Two charts break the same data down further. Both appear under Retention & Churn in Charts, and only for iOS apps, since Apple's Retention Messaging API is iOS only.

• Retention Messaging Save Rate: percentage of sent messages where the subscriber did not cancel within 24 hours.
• Retention Messaging Saves: count of saved subscriptions, broken down by what the subscriber did next.

Both charts support breakdowns by Product, Environment, Retention Message, Retention Configuration, Response Type, Retention Locale, Retention Campaign, Retention Audience, Retention Variant, Retention Selection, and Save Outcome. Every one of those except Save Outcome can also be used as a filter, along with Retention Message Group and Retention Configuration Group.

How sends and saves are counted

• A message sent is one realtime request from Apple that Superwall answered with a message, a switch plan, or a promotional offer. Requests answered with no match, and requests that errored, are not counted.
• Sends are deduplicated to one per subscription per calendar day in UTC, keeping the last message served that day. A subscription messaged on three separate days counts as three sends.
• A send is a save when no cancellation is recorded for that subscription within 24 hours of the message.
• Rates across a multi-day range are recomputed from the summed counts rather than averaged across days.