Android

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: Churn IQ Dashboard relies on offer prices manually defined at Cleeng (the prices have to be mirrored between systems).

📘

Important

Please note that you must offer In-App payments for the services delivered in your native apps (see Google 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 /android/payment endpoint in your integration that utilizes JWT, middleware is not needed.

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

2. Typical System Architecture

Below you can see the overview of the typical system architecture. It shows the interaction - data exchange - between your app, Google Play, your middleware and Cleeng.

For details, see Sequence Diagram.

Subscription Receipt

Google uses Subscription Purchase Resource for providing information about the status of a user’s subscription purchase. For purposes of this tutorial, we shall refer to it as a receipt.

A receipt is a digital “document” confirming a subscription purchase. It is stored in the Cleeng database.

Receipt’s features:

• It is provided to Cleeng during an initial purchase
• It consists of subscription details
• It is a single source of truth for Cleeng - verifiable at any time in Google.

3. Prerequisites

To start with the setup, please follow the steps:

1. Set up a Google Play developer account, create an application and create your products - see Google Docs.

🚧

Warning

In May 2022 changes were introduced to the way subscription products are defined in Play Console. With reference to these changes, please note that you need to use backward compatible subscriptions to ensure compatibility with Cleeng (see more in the article Changes to Subscription Products in Google Console).

For more information regarding backward compatible offers, see Google documentation.

📘

Important Note

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

Example of offer equality:

🚧

Remember to add your Google Play 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.

2. Integrate the Google Play Billing Library (for more information, see here).

4. Provide a service account key

Cleeng requires a service account key in JSON format to keep subscribers synchronized between Google Play Store and Cleeng.

The Google Cloud service account should be created with permission to use Google APIs on behalf of a Google Play user, with specific privileges. Once you have the service account with the right privileges, you can create the JSON API key.

Please follow the instructions:

1. In the Google Cloud Console, select the right project, and make sure you have enabled access to the Google Play Android Developer API by clicking Enable (it says Manage when already enabled).

2. Then go to Service Accounts, click Create service account, and follow the steps.
   a) Copy-paste the Service account ID (an email address) to use later in step 5.
   b) Under Grant this service account access to project select Basic ⇒ Owner (see the screenshot below).

   

   You have created a service account within Google Cloud. Now we grant this user permissions to the Google Play Store.

3. Go to the Users & Permissions page on the Google Play Console.

4. Click Invite new users.

5. Put the email address for your service account (see step 2a) in the email address field and grant the necessary rights to perform actions. You must grant the following permissions:
   a) View app information and download bulk reports (read-only)
   b) View financial data, orders, and cancellation survey responses
   c) Manage orders and subscriptions

   See also the screenshot below:

   

6. Click Invite user.

   At this point, you have the permissions to access the Google Play Developer API through this service account. Though in order to do so, you require a key.

7. In the Google Cloud Console go back to Service Accounts.

8. Click on the email address of the service account for which you want to create a key.
   a) Go to the Keys tab.
   b) Select Add Key.

9. Choose Create new key from the drop-down menu.

10. Choose JSON as the Key type and then click Create. Clicking Create downloads the JSON file (a service account key file). Please note that it cannot be downloaded again.

    

You need to deliver the service account key to our Support Team to finalize Android in-app purchase setup and enable the synchronization of Google Play In-App subscribers to Cleeng.

Note:

Credentials can take up to 24 hours after being created to be valid.

Also, if you have added your in-app products before granting permission or linking to your service account, you might need to make a change in in-app products (e.g. create and activate a new product) for receipt validation with Google Play Android Developer API to work properly.

You can read more about this topic in Google Developer Documentation.

5. Implementation

Note:
We recommend using our 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 Android application is responsible for displaying the “Buy” button that will initiate the payment. Because it is an In-App purchase, payment is made outside of Cleeng.

Once payment is completed, Google Play returns a purchase Token that must be passed to the Cleeng's payment endpoint /android/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. Receipt Validation

Access to content is based on a receipt. That's why a receipt needs to be properly validated before access is granted.

Validation is done automatically by Cleeng. It might take some time.

Receipt processing is an asynchronous process. Even though 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, content can be revealed.

The flowchart below shows the process:

7. Purchase Acknowledgement

The Client application needs to use the Google Play Billing Library to acknowledge the initial purchase.

You need to make sure that the purchase is acknowledged, because if it is not acknowledged within three days, the customer will receive a refund, and Google Play will revoke the purchase (see Google Documentation).

8. Sequence Diagram

The diagram below provides more information about integration.

(*) Purchase acknowledgement can be done either before of after calling Cleeng API.

9. Real-time developer notifications

It is direct one-way communication between Google Play and Cleeng. It provides real-time subscription updates.

The table below presents which Real-time notifications are supported:

You need to make a pub/sub queue on Gcloud and provide a URL address for notifications.

📘

The URL you need to provide is:

• https://notification.cleeng.com/2.0/in_app/subscriptions/android/status_update_notification/{publisherId} (production environment)
• https://notification.sandbox.cleeng.com/2.0/in_app/subscriptions/android/status_update_notification/{publisherId} (sandbox environment)

You need to replace {publisherId} with your publisher ID in the URL.

This will add consumer to consumer queue which will be sending notifications to Cleeng.
For information on how to make pub/sub queue, see Set up in Google Play Store.

Set up in Google Play Store

Follow these steps to configure pub/sub queue in Google:

1. Login to your Google Cloud Account
2. Go to the Topic List and choose your Android project.
3. Create a topic:

Note:
realtime_notification topic name is not mandatory, you can choose your own topic id.

4. Create a subscription:

Note:
realtime_notification subscription id is not mandatory, you can choose your own subscription id.

• In the Select a Cloud Pub/Sub topic menu you need to choose the one you have created in the previous step.

• Change Delivery type from “pull” to “push” and add Cleeng notification URL:

  • https://notification.cleeng.com/2.0/in_app/subscriptions/android/status_update_notification/{publisherId} (for production environment), or
  • https://notification.sandbox.cleeng.com/2.0/in_app/subscriptions/android/status_update_notification/{publisherId}(for sandbox environment)

• Enable Authentication - JSON Web Token (JWT) Authentication must be configured in Google Pub/Sub subscription in such a way that JWT signed by Google is attached to each notification. Service account is the publisher's service account. Audience should be set to:

  • https://notification.cleeng.com (for production environment), or
  • https://notification.sandbox.cleeng.com (for sandbox environment).
    For more information on how to set it up please refer to Google documentation.

• Retry policy should be set to "Retry after exponential backoff delay". The screenshot above shows the recommended values.

5. Come back to the Topic list and go to the View permissions submenu:

6. Click Add member and add [email protected] with Pub/Sub Publisher permission.

7. Go to https://play.google.com/console/ and choose your application.
8. Go to the Monetization setup section and add your topic name in the Real-time developer notifications section. You can copy your topic name from the topic list in the Gcloud console.
9. Click Test notification. If no errors are returned, save settings.

Subscription Upgrades and Downgrades

The following algorithms are supported:

• IMMEDIATE_AND_CHARGE_FULL_PRICE - for subscription upgrades.
  The algorithm upgrades the current subscription and the customer is charged full price for the new subscription immediately. The new billing cycle starts with the switch. The remaining value from the previous subscription is prorated for time and added at the end of the billing cycle (the next charge is delayed).
• DEFERRED - for subscription downgrades.
  The subscription switch 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.

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 Android, Coupons Campaign mechanisms are used. As a result, discounts can be applied to all new subscriptions that are created based on a given offer, on condition that a coupon code has been properly passed in the initial purchase.

To use the feature, you need to:

1. Set up a proper coupon campaign that matches the discount in Android
2. Send a proper couponCode in Initial Purchase.

Set up Proper Coupon Campaign

You need to configure a proper coupon campaign in the 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 Android is discounted for two months -> you need to create a coupon campaign for this offer in Cleeng with appropriate % discount (to mirror the discounted price in Android) 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.

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

Please follow these steps to test the initial payment configuration:

1. Configure testing environment in Google Play - see Google Documentation
2. Create a Cleeng sandbox account (or log in if you already have one) and create a test offer.
3. Make sure Google and Cleeng offers in a sandbox environment are compatible.
4. Provide the service account key to the support team (see the Provide a Service Account Key section).
5. Make an initial purchase and verify that the purchase has been acknowledged.
6. Make a request to Cleeng's Payment Endpoint: Sandbox URL: https://api.sandbox.cleeng.com/android/payment.
7. Content should be revealed.

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

The way to reconcile reporting is to configure a matching offer at Cleeng. So please remember that if you use a configuration in Google that you haven't configured at Cleeng, then reporting will run out of sync.