Apple iOS & tvOS

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 ArchitectureTypical System Architecture

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 EqualityOffer 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 payment endpoint /apple/payment.

This endpoint includes a subscription transfer feature. It is triggered when:

  • we already have an active subscription for the provided receipt
  • this subscription belongs to a customer ("old customer") with a different email address than the one for which this request is being made ("new customer").

The subscription transfer feature creates a new subscription for the "new customer" (the one using the new e-mail address) and terminates the subscription assigned to the "old customer" (the one using the old email address).

Purchase FlowPurchase Flow

Purchase Flow

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 AccessValidating Access

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 DiagramSequence Diagram

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: RenewalServer-2-Server Communication: 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. Introductory Offers

An introductory offer is a limited-time discounted price for the initial period of a subscription.

To make Cleeng’s discounts setup consistent with introductory offers on Apple, Coupons Campaign mechanisms are used. As a result, discounts are applied to all new subscriptions that are created based on a given offer.

To use the feature you need:

  1. Set up a proper coupon campaign that matches the discount in Apple - i.e. apply proper coupons to every subscription created on a selected offer.
  2. Send a proper couponCode in Initial Purchase.

Set up Proper Coupon Campaign

You need to configure a proper coupon campaign in Cleeng Dashboard.
To do this, go to Offers & Coupons - > Coupon Management section. (For more information on coupon campaigns, visit here.

Example:
The price of an offer in Apple is discounted by 50% for two months -> you need to create a coupon campaign for this offer in Cleeng with 50% for two billing cycles.

Make sure to create a separate coupon campaign for each offer.

Note:
Use a generic coupon campaign (in Coupon Campaign settings select: “Number of coupons: One”).

Send a Proper couponCode in Initial Purchase

If you want to use introductory offers, you need to add an additional payload parameter - couponCode - to the requests.

It is a coupon code applied for this purchase. The code shall be sourced from the coupon campaign properly created and assigned to the offer in the Cleeng dashboard.

JSON payload example:

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

Important Note:
If a coupon is invalid, the payment will be processed despite this, but the discount will not be applied.

📘

Good to Know

Recurring payments will use coupons automatically.

11. 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, then reporting will run out of sync. Be noted that the entitlements synchronization between Cleeng and Apple would still work.


Did this page help you?