Subscription attribution guide

Introduction

If your app offers subscription-based features, you can record subscriptions and subscription renewals with AppsFlyer.

Recording subscriptions can help you calculate revenue and ROI, as well as highlight successful campaigns. By gathering subscription related data, you can decide which subscriptions offer more value, and which media sources bring more subscribing users.

Ways to record subscription events

There are two ways to record subscription-related events in AppsFlyer: Server-to-Server Events and In-App Events (sent directly from the app). Each approach has its advantages and disadvantages which are discussed in the table below. This can help you decide which approach suits you better.

Topic	Server-to-Server	In-App Events
Event dependence on the app	The event is sent from the server and is not dependent on the app to be launched.	The event is sent from the app which means that the app must be launched
Implementation	Requires backend logic to handle subscriptions Requires backend logic to send events to AppsFlyer using API	Implemented using the SDK Can be implemented once in the app for all users
Data accuracy	The event is sent in real-time at the time of subscription creation or renewal When sending a set of events simultaneously, you still have control over the event timestamp Accurate subscription and subscription renewal timestamps Accurate revenue data	Events are only sent when the app is launched Subscription time and event time might differ Less control over the event Some events might be missing Revenue data might not be accurate
Identifying subscribing users	Requires you to cross-reference data in order to identify the actual user for whom a subscription was renewed	Easy to identify the user for whom a subscription is created or renewed The SDK allows you to easily identify the user

Server-to-server subscription event

With server-to-server events, you can record subscription events in real-time without depending on the user's app to be launched. To implement server-to-server events, you need to design backend logic. The backend logic keeps track of subscriptions (new and renewed) and sends subscription events to AppsFlyer as necessary.

Sending server-to-server events to AppsFlyer for subscription notifications

AppsFlyer by default doesn't receive notifications of renewal or subscription events from the app stores. This section discusses how to set up a connection to the respective app store and pass subscription information to AppsFlyer as a server-to-server event.

Managing subscriptions on Android can be done on the App and Server levels. On the App level, communication is done through Google Play Billing Library. On the Server level while it is done through Google Play Developer API. The recommended way for managing subscriptions is through Google Play Developer API. This is the way that is discussed in this article.

Step 1: Set up the server endpoint to receive subscription-related notifications

Create a server endpoint that receives subscription-related notifications from Google Cloud. Then, enable real-time developer notifications:

Determine a URL endpoint on your server to use for subscription status updates. For example, https://myserver/subscription-notifications.
Set up Cloud Pub/Sub in your Google Cloud Platform (GCP) project.
Enable real-time developer notifications for your Android app.

Step 2: Handle real-time subscription notifications

Once you set up a server endpoint to receive notifications, write the logic to handle these notifications. By default, Google sends notifications through Pub/Sub with subscriptionId and purchaseToken. The notification message doesn't contain any relevant information about the actual subscription. You need to take the purchase token and send a request to the Google Play Developer API to purchases.subscriptions.

The subscription notification contains the following:

{
	"version": string,
	"packageName": string,
	"eventTimeMillis": 1578509686,
	"subscriptionNotification": SubscriptionNotification,
	"testNotification": AppsFlyerTest
}

In the subscription notification, there's an object called SubscriptionNotification. It contains the following.

{
	"version": 1.0,
	"notificationType": 4,
	"purchaseToken": 0f43308f-bf3f-4fa1-8aef-d515c941334b,
	"subscriptionId": 123456789
}

purchaseToken is the token that you send to Google Play Developer API to purchases.subscriptions get data about the subscription.

The subscriptionId is the value you store into your database and associate it with the AppsFlyer ID.

Step 3: Associate subscription with Appsflyer ID and GAID in your database

Once you get the data about the subscription, you need to set up a link between the subscription ID and the AppsFlyer ID and GAID. The AppsFlyer ID is mandatory for sending server-to-server events to AppsFlyer. We strongly recommend to include the GAID when sending a server-to-server event. Including it allows AppsFlyer to send event postbacks to SRNs (self-reporting networks). It also opens for you the option to use AppsFlyer Audiences. You can get the AppsFlyer ID and GAID in one of the following ways:

The complete Android subscription attribution flow

See the following flowchart for the complete subscription attribution flow:

Getting notified about a subscription status change.
Associating a subscription with AppsFlyer ID and GAID.
Sending a subscription-related event to AppsFlyer.

Apple calls its service Server-to-Server notifications. This service is designed specifically for auto-renewable subscriptions. The App Store sends notifications of real-time changes in a subscription's status. You can use these notifications and their data to send subscription-related events to AppsFlyer.

Step 1: Set up the server endpoint to receive subscription-related notifications

Set up a server endpoint that receives post requests. Configure the endpoint as follows:

Support App Transport Security (ATS) on your server. The App Store must establish a secure network connection with your server by using ATS protocols before sending notifications. For more information, see preventing insecure network connections.
Determine a URL endpoint on your server to use for subscription status updates. For example, https://myserver/subscription-notifications.
Configure the subscription status URL for your app in App Store Connect. For guidance, see Enable status notifications for auto-renewable subscriptions.

Step 2: Connect the server endpoint to your app:

Once the endpoint is configured, input the server URL in the Subscription Status URL field in App Store Connect:

Step 3: Receive the notification and associate it with AppsFlyer IDs and IDFA in your database

Now you are ready to receive notifications from Apple about subscriptions. See the following sample notification:

{
    "latest_receipt": "ewoXXXXX",
    "latest_receipt_info": {
        "original_purchase_date_pst": "2019-07-29 21:13:18 America/Los_Angeles",
        "quantity": "1",
        "unique_vendor_identifier": "XXX",
        "original_purchase_date_ms": "1564459998000",
        "expires_date_formatted": "2019-08-06 04:13:17 Etc/GMT",
        "is_in_intro_offer_period": "false",
        "purchase_date_ms": "1564459997000",
        "expires_date_formatted_pst": "2019-08-05 21:13:17 America/Los_Angeles",
        "is_trial_period": "true",
        "item_id": "1452171111",
        "unique_identifier": "00000",
        "original_transaction_id": "0000000",
        "expires_date": "00000000",
        "app_item_id": "0000000",
        "transaction_id": "00000000",
        "bvrs": "00000",
        "web_order_line_item_id": "00000000",
        "version_external_identifier": "000000",
        "bid": "com.XXX",
        "product_id": "XXXXX",
        "purchase_date": "2019-07-30 04:13:17 Etc/GMT",
        "purchase_date_pst": "2019-07-29 21:13:17 America/Los_Angeles",
        "original_purchase_date": "2019-07-30 04:13:18 Etc/GMT"
    },
    "environment": "PROD",
    "auto_renew_status": "true",
    "password": "*****",
    "auto_renew_product_id": "com.XXXX",
    "notification_type": "INITIAL_BUY"
}

Important!

The data from Apple's Status Update Notification doesn't contain the subscription price. You should implement backend logic to match the notification from Apple with the correct subscription price.

You use this data to send subscription-related events to AppsFlyer. To do so, you need to associate a subscription with an AppsFlyer ID and IDFA. We strongly recommend to include the IDFA when sending a server-to-server event. Including it allows AppsFlyer to send event postbacks to SRNs (self-reporting networks). It also opens for you the option to use AppsFlyer Audiences.

You can get the AppsFlyer ID and GAID in one of the following ways:

The complete iOS subscription attribution flow

See the following flowchart for the complete subscription attribution flow:

Getting notified about a subscription status change.
Associating a subscription with AppsFlyer ID and IDFA.
Sending a subscription-related event to AppsFlyer.

Sending the event to AppsFlyer

At this point, you have knowledge of a subscription status change (purchase, renewal, cancellation) and have associated it with an AppsFlyer ID. Now, make sure the following takes place:

Your server gathers the necessary data for the event. Such data should include the following: revenue, subscription type, subscription ID (item_id in the data from Apple), AppsFlyer ID, time of renewal. Recommended mapping (see the code snippet below):
- af_revenue: revenue
- af_content_type: subscription type
- af_content_id: subscription ID (item_id in the data from Apple)
- renewal: true/false (based on subscription status change)
- eventTime: the time the notification reaches your server
Based on the type of event (purchase, renewal, cancellation), the server sends the event to AppsFlyer as a subscription event with all related data.

Formatting and sending the event

Subscription event request example:

HTTP POST https://api2.appsflyer.com/inappevent/<APP_ID>
HTTP/1.1
headers:
{
  authentication: '<YOUR_DEV_KEY>',
  Host: 'api2.appsflyer.com',
  Accept: 'application/json',
  'Content-Type': 'application/json'
}
body: 
{
  "appsflyer_id":"<APPS_FLYER_ID>",
  "customer_user_id":"123456",
  "eventName":"af_subscribe",
  "eventValue":"{\"af_revenue\":\"200\",\"af_content_id\":\"092\", \"af_content_type\": \"123\", \"renewal\":\"true\"}",
  "eventCurrency":"USD",
  "ip":"1.0.0.0",
  "eventTime":"2018-07-09 4:17:00.000",
  "af_events_api":"true"
}

To learn how to format and send the event to AppsFlyer, see sending server-to-server events.

In-app subscription event

Apps often need to check subscription status in order to enable subscription-specific features. You can use this mechanism in order to send subscription-related events to AppsFlyer. Once the app is aware of a subscription purchase or renewal, it can send the event.

Warning

If a user subscribes but doesn't launch the app for more than a month, the subscription is not counted as an event. For example, a user subscribes through your website but then doesn't open the app. If the user doesn't open the app for more than a month after subscribing, the subscription is not counted.

Checking subscription status in the app

The app can either communicate with your servers or receive push notifications with data about subscriptions.

You can configure your app to check the status of the subscription. There are two ways you can achieve this:

The app checks the subscription status and related data (active or not active, subscription type, expiration date etc.)
The app receives a push notification about a subscription purchase or renewal.

Tip

For Android applications: you can use Android's real-time developer notifications to notify the app about renewals in real-time.

For iOS applications: the Store kit provides you with payment queue and transaction observers. You can use these to verify a subscription purchase or renewal. Refer to Apple's documentation on finalizing transactions for more information.

Note

Receipt validation is not supported for recording subscriptions in iOS applications.

Sending a subscription-related in-app event

Once the app has the relevant subscription-related data, the following steps should take place:

The app checks to see if the subscription is a purchase or renewal.
The app gathers the relevant data (revenue, content_id, purchase or renewal, etc.).
The app sends the subscription event to AppsFlyer using the SDK.

Subscription event example

Parameter Name	Type	Example of Value	Description
af_revenue	float	200	The revenue associated with the subscription
af_currency	string	USD, GBP	The currency of the payment
af_content_id	string	092, monthly_subscription	The name or code of the subscription
renewal	boolean	true, false	whether the subscription is new or renewed

Event code samples

The code snippet below demonstrates how to configure and send the event using the SDK.

Map<String, Object> eventValue = new HashMap<String, Object>();
eventValue.put(AFInAppEventParameterName.REVENUE, 200);
eventValue.put(AFInAppEventParameterName.CURRENCY, "USD");
eventValue.put(AFInAppEventParameterName.CONTENT_ID, "092"); 
eventValue.put("renewal", true); 
AppsFlyerLib.getInstance().trackEvent(getApplicationContext(), AFInAppEventType.SUBSCRIBE, eventValue);

[[AppsFlyerTracker sharedTracker] trackEvent:(AFEventSubscribe) withValues: @{
  AFEventParamRevenue: @200,
  AFEventParamCurrency: @"USD",
  AFEventParamContentId: @"092",
  @"renewal": @TRUE
}];

AppsFlyerTracker.shared().trackEvent(AFEventSubscribe, withValues: [
  AFEventParamRevenue: 200,
  AFEventParamCurrency: "USD",
  AFEventParamContentId: "092",
  "renewal": true
]);

Dictionary<string, string> SubscriptionEvent = new Dictionary<string, string>();
SubscriptionEvent.Add("af_revenue", "200");
SubscriptionEvent.Add("af_currency", "USD");
SubscriptionEvent.Add("af_content_id", "092");
SubscriptionEvent.Add("renewal", "true");
AppsFlyer.trackRichEvent ("af_subscribe", SubscriptionEvent);

Note

It is highly recommended that you associate subscriptions with customers. To do so, make sure to set the customer user ID. Setting the customer user ID is your way to match your customers with users of your app as they appear in AppsFlyer. By setting the customer user ID you make sure that any event, subscription-related events included, is sent with the customer user ID.

Introduction

Ways to record subscription events

Server-to-server subscription event

Sending server-to-server events to AppsFlyer for subscription notifications

Step 1: Set up the server endpoint to receive subscription-related notifications

Step 2: Handle real-time subscription notifications

Step 3: Associate subscription with Appsflyer ID and GAID in your database

The complete Android subscription attribution flow

Step 1: Set up the server endpoint to receive subscription-related notifications

Step 2: Connect the server endpoint to your app:

Step 3: Receive the notification and associate it with AppsFlyer IDs and IDFA in your database

Important!

The complete iOS subscription attribution flow

Sending the event to AppsFlyer

Formatting and sending the event

In-app subscription event

Warning

Checking subscription status in the app

Tip

Note

Sending a subscription-related in-app event

Subscription event example

Event code samples

Note

Articles in this section

Page contents:

Subscription attribution guide

Introduction

Ways to record subscription events

Server-to-server subscription event

Sending server-to-server events to AppsFlyer for subscription notifications

Step 1: Set up the server endpoint to receive subscription-related notifications

Step 2: Handle real-time subscription notifications

Step 3: Associate subscription with Appsflyer ID and GAID in your database

The complete Android subscription attribution flow

Step 1: Set up the server endpoint to receive subscription-related notifications

Step 2: Connect the server endpoint to your app:

Step 3: Receive the notification and associate it with AppsFlyer IDs and IDFA in your database

Important!

The complete iOS subscription attribution flow

Sending the event to AppsFlyer

Formatting and sending the event

In-app subscription event

Warning

Checking subscription status in the app

Tip

Note

Sending a subscription-related in-app event

Subscription event example

Event code samples

Note

Articles in this section

Related articles

Page contents: