Apple In-App Purchase - SK1

🚧

This documentation is for legacy Apple in-app purchase integration utilizing Apple’s StoreKit 1. For a tutorial on new integration of Apple in-app purchases, please visit Apple In-App Purchase - StoreKit 2 [Beta].

Please refer to Apple documentation for information about which Apple platforms and versions are supported for StoreKit 2.

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).

🚧

Important

Please note that middleware is required in integrations utilizing a publisher token.

The tutorial below focuses on the integration when a publisher token is used, so middleware is also included.

If you use the MediaStore SDK /apple/payment endpoint in your integration that utilizes JWT, middleware is not needed.

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.

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 a developer account with Apple (see more in Apple documentation) and create an application.
2. Add test products - see Apple documentation.

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

📘

Important notes for setting up products compatible with Cleeng:

• The product price must be set manually in App Store Connect. Be sure to align prices between Apple's product and your Cleeng offer.
• You can only select price tiers in App Store Connect; make sure the offers 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 App Store Connect on your phone and log in with one of the sandbox accounts created in App Store Connect -> Users and Access -> Sandbox Testers.

Example of offer equality:

Remember to add your App store product ID in the offer setup in the dashboard in order to map the external offer properly in the Cleeng system. For more information, see this article.

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.

You need to deliver the generated shared secret key to our Broadcaster Success Specialists team to enable the Apple iOS & tvOS functionality.

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).

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).

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 Get Entitlements 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:

7. Testing

Please follow these steps to test the initial payment configuration:

1. Configure in-App purchase in App Store 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 App Store 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.

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} (production environment)
• https://notification.sandbox.cleeng.com/1.0/in_app/subscriptions/apple/status_update_notification/{publisherId} (sandbox environment)

Replace {publisherId} with your publisher ID in the URL.

The table below presents which Apple notifications are supported:

Server-2-Server Notifications: Renewal

See below the example of server-2-server notification for the process of subscription 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. Subscription upgrades and downgrades

Upgrades

Upgrades work as follows:

• A subscription is upgraded immediately.
• The customer gets access to the new plan.
• The customer is charged full price for the new plan immediately.
• The billing cycle is changed and starts at the moment of the subscription upgrade.

Upgrades during free trial

• The new subscription is initiated.
• The original subscription is terminated. This results in losing the free trial by the customer.

Downgrades

Downgrades work as follows:

• A subscription downgrade happens only when the subscription renews.
• The customer is charged full price for the new plan at the start of the next billing cycle.
• The billing cycle remains unchanged.

12. 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.