Contents

Setting up your Get Retention Message endpoint

Choose retention messages for customers in real time by implementing an endpoint on your server that responds to requests from the App Store server.

Overview

To receive requests from the App Store so that you can provide retention messages in real time, complete the following:

  1. On your server, implement a Get Retention Message endpoint to the specifications described below.

  2. Configure your endpoint for the sandbox environment by calling the Configure Realtime URL endpoint.

  3. Call the Initiate Performance Test, which runs in the sandbox environment. Your server needs to pass the test before you can configure your endpoint for the production environment.

  4. Configure your endpoint for the production environment by calling the Configure Realtime URL endpoint.

After you set up the Get Retention Message endpoint, the App Store server delivers real-time requests when customers view a subscription detail page where they may choose to cancel the subscription. You respond to the request by choosing a retention message for the system to display to the customer. You set up the retention messages in advance. The system only displays messages that have an APPROVED state. If the message includes an image, the image also needs to have an APPROVED state.

Your server is responsible for parsing, interpreting, and responding to all server-to-server posts. For information about responding to requests, see Responding to real-time retention messaging requests.

Implement your endpoint

Implement this endpoint on your server to the following specifications:

Endpoint reference name: Get Retention Message

URL: POST https://example.com/<your URL>

You determine the HTTPS URL(s) on your server to receive the requests for the sandbox and production environments. Share your URLs with Apple by calling the Configure Realtime URL endpoint.

HTTP body: RealtimeRequestBody

The request body. For the decoded version, see DecodedRealtimeRequestBody.

Response codes: 200 - OK RealtimeResponseBody Your response body identifies the retention message to display to the customer.

If a request fails for any reason, the system displays a default retention message. If a default message isn’t available, the system doesn’t display a retention message. For more information about default messages, see Setting up retention messages.

Implement the server requirements

Set up secure communications with the App Store server by meeting the following requirements:

  • Your domain must have a valid SSL certificate.

  • Your endpoint must implement TLS 1.2.

  • Your endpoint needs to respond within 700 ms in the production environment; otherwise, the App Store server times out and the request fails.

Configure your endpoint for real-time use

To configure your Get Retention Message endpoint with this API’s server, call the Configure Realtime URL endpoint. Set up the endpoint in the sandbox environment first.

To check the URL you configured, call the Get Realtime URL endpoint.

To remove your endpoint from real-time use, call the Delete Realtime URL endpoint.

See Also

Real-time retention messaging setup