Apple iOS & tvOS Integration

1. Overview

In-App integration enriches your portfolio with one more payment method for your services. Users can buy your products directly in your application, which makes the process easier. It also provides added value to you.

When you enable In-App purchases you gain:

  • multi-access for your users - they can use your services on many devices

  • enhanced reporting for you - all-in-one-place reporting that can support your subscriber retention analytics and strategy building.

    Note: ChurnIQ Dashboard relies on In-Apps receipts for reporting.

πŸ“˜

Important

Please note that you must offer In-App payments for the services delivered in your native apps as per Apple Terms & Conditions (see Apple Documentation).

Please follow this guide for smooth iOS In-App integration.

2. Typical System Architecture

Below you can see the overview of the typical system architecture. It shows the interaction between your app, Apple AppStore, the middleware, and Cleeng. with the receipt exchange playing a major role.

Typical System Architecture

For details see Sequence Diagram.

Subscription Receipt Exchange

Receipt is a digital β€œdocument” confirming subscription purchase. It is stored in the Cleeng database.

Receipt’s features:

  • It is exchanged as a payload of APIs and messages
  • It is provided to Cleeng during initial purchase
  • It contains a unique IAP subscription identifier
  • It consists of transactions data and subscription details
  • It is a single source of truth for Cleeng - verifiable at any time in Apple
  • It is used in all IAP flows
  • Subscription price is not present in Apple Receipt.

3. Prerequisites

To start with the iOS setup, middleware should be connected to Apple In-App Purchase. To do so, please follow the steps:

  1. Set up an Apple iTunes Connect account and create an application - see Tutorial
  2. Add test products - see Tutorial

Products that you add must be compatible with your Cleeng offer.

πŸ“˜

Important notes for setting up products compatible with Cleeng:

  • The product references must be the same as Cleeng's offer IDs.
  • The product price must be set manually in iTunes Connect. Be sure to align prices between Apple's product and your Cleeng offer.
  • You can only select price tiers in Apple iTunes Connect; make sure the videos in the Cleeng database have the same price.
  • Use non-renewing-subscription products for subscriptions set for a specific period of time. The subscriptions are removed from the receipt after the App has retrieved access to the product automatically. This means that the application must rely on Cleeng when checking entitlement.
  • Use non-consumable for subscriptions that are forever. They will remain on the receipt forever.
  • To test the setup, log out of Apple iTunes Connect on your phone and log in with one of the sandbox accounts created in iTunes Connect -> Users and Roles -> Sandbox Testers.

Example of offer equality:

Offer Equality

4. Provide Apple Key

By now, you have probably generated a shared secret for all your apps (primary shared secret) or for an individual app (an app-specific shared secret) - see Apple documentation.

Provide the generated shared secret key to the BSS team.

The key is required for Apple - Cleeng communication.

5. Implementation

Note:
We recommend using MediaStore API (for more information see Getting started), especially for authentication (registration and login). If any of the specific functions are missing with MediaStore API, you can fall back to JSON RPC (see more: Getting Started With JSON-RPC).

Register User

The application attempts to log in the user (see Log in User). If the user doesn't exist, registration is required. It is recommended that the application uses the Register method to register the customer. For more information see Registration.

Log in User

If the user exists, it is recommended that the application uses the Login endpoint to log in. For more information see Login.

Make Initial Purchase

The iOS application is responsible for displaying a Buy button that will initiate the payment (see Apple documentation). Because it is an In-App purchase, payment is made outside of Cleeng. The details of transactions are available to Cleeng thanks to a receipt.

Once payment is completed, the App Store returns a receipt object that must be passed through the middleware to Cleeng's Receipt Endpoint. For details see Communication with the Receipt Endpoint.

Purchase Flow

Communication with the Receipt Endpoint

Once successful payment is completed through Apple Billing, the Cleeng receipt endpoint must be notified.

The relevant endpoints are:

πŸ“˜

Production URL: https://cleeng.com/apple/payment
Sandbox URL: https://sandbox.cleeng.com/apple/payment

Request

This section describes the request.

Request method: POST

Required headers:

Content-Type: application/json
X-Publisher-Token: publisher_token

JSON payload example

{
    "customerEmail": "[email protected]",
    "offerId": "S598742062_US",
    "receipt": {
        "transactionId": "1234565432",
        "receiptData": "receipt_data"
    },
    "appType": "app_type",
    "ipAddress": "192.168.1.1"
}

Parameters

The payload parameters are as follows,

Parameters

Description

customerEmail

End-user email

offerId

An Identifier for Cleeng offer (e.g. E123123123_US )

transactionId

Last used transaction identifier returned from the iTunes store

Warning: This is not the initial transactionId.

receiptData

complete receipt data returned from the iTunes store

appType

Apple device, either ios or tvos

ipAddress

the viewer IP address (optional parameter)

Example json response:

{
    "message": "OK"
}

Response description

message - processing result

HTTP status codes

The following codes may be returned:

Error Code

Description

400

Invalid Parameters

401

Invalid authentication/broadcaster and viewer

422

Unprocessable entity

200

OK

500

Internal server error

6. Validate Receipt

Access to content is based on a receipt. Cleeng validates the receipt before access is granted.

Receipt processing is an asynchronous process. Even that most responses are within 3 seconds, they can take up to 60 seconds.

The application should poll the Cleeng API using the getAccessStatus or getAccessibleTags method every five seconds until validation is completed.

  • If access is not granted within 60 seconds, the application should assume it failed and inform the user accordingly.
  • If the transaction is confirmed, video content can be revealed.

The flowchart below shows the process:

Validating Access

7. Testing

Please follow these steps to test the initial payment configuration:

  1. Configure in-App purchase in Apple iTunes Connect - see Apple Documentation
  2. Create Cleeng sandbox account (or log in if you already have one) and create a test offer.
  3. Make sure Apple iTunes Connect and Cleeng offer in sandbox environment are compatible - for more information see "Important notes for setting up products compatible with Cleeng" above.
  4. Provide a shared secret key to the BSS team.
  5. Make an initial purchase.
  6. Receipt object must be passed through the middleware to Cleeng's Receipt Endpoint: Sandbox URL: https://sandbox.cleeng.com/apple/payment
  7. Video should be revealed

8. Sequence Diagram

The diagram below provides more information about integration.

Sequence Diagram

9. Server-2-Server Notifications

Server-2-Server Notifications is direct one-way communication between Apple AppStore and Cleeng. It provides near real-time subscription updates.

You need to provide a URL address in App Store Connect for server-to-server notifications - see Apple documentation.

The URL you need to provide is: https://notification.cleeng.com/1.0/in_app/subscriptions/apple/status_update_notification/{publisherId}. Replace {publisherid} with your publisher id in the URL.

The table below presents which Apple notifications are supported:

Apple Notification

Supported at Cleeng

CANCEL

βœ“

DID_CHANGE_RENEWAL_PREF

βœ—

DID_CHANGE_RENEWAL_STATUS

βœ“

DID_FAIL_TO_RENEW

βœ“

DID_RECOVER

βœ“

DID_RENEW

βœ“

INITIAL_BUY

βœ—

INTERACTIVE_RENEWAL

βœ“

PRICE_INCREASE_CONSENT

βœ“

REFUND

βœ“

RENEWAL (DEPRECATED IN SANDBOX)

βœ“

REVOKE

βœ“

Server-2-Server Notifications: Renewal

See below the example of server-2-server notification for the process of subscription renewal.

Server-2-Server Communication: Renewal

Processes that occur after initial payment are fully automated. Cleeng renews subscriptions automatically, based on notifications and an additional supporting system - renewal timer.

10. Good to know

πŸ“˜

Good to know

Any mechanisms that influence the final amounts paid by end-users (e.g. promotional offers) cause a difference between the offer price and the actual amount paid. Please note that Apple doesn't provide the actual price paid by a specific end-user. This is neither available through reporting APIs, nor through their system receipts as described here.

The way to reconcile reporting is to configure a matching offer at Cleeng. So please remember that if you use a configuration in Apple that you haven't configured at Cleeng (like intro offers), then reporting will run out of sync. Be noted that the entitlements synchronization between Cleeng and Apple would still work.

Updated 7 days ago


Apple iOS & tvOS Integration


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.