App Management setup

Connect your Apple App Store and Google Play apps to Recurly App Management to track subscription lifecycles, then configure external products, entitlements, and webhooks.

To give you a complete view of your app subscription lifecycles and their revenue, Recurly needs two things: the real-time notifications from Apple and Google, and API access to retrieve key subscription info. This one-time setup connects your mobile apps to Recurly. Work through the platform you use — Apple, Google, or both — then finish with external products, entitlements, and webhooks.

1Connect your apps 2Configure App Management 3Migration

Before you beginRead through the App Management key details before connecting Apple or Google. You may need to make slight modifications to the subscription purchasing workflow in your mobile apps.

Connect your mobile apps

Choose your platform below. If you offer subscriptions on both, complete each tab.

Prerequisites

Before configuring Recurly App Management, create a new Apple App Store Connect API key with the right permissions. You'll need to be an Account Holder or Admin in Apple App Store Connect to complete these steps — if you hit permission issues, reach out to one of your Apple App Store Connect Admins.

Log into App Store Connect

Log into Apple App Store Connect. You'll be creating an App Store Connect API key — not an In-App Purchase key — for the Recurly connection.

Create an API key

Select the + (plus) symbol near "Active." Enter a name to uniquely identify the key, and for Access select both Developer and Sales and Reports. Then select Generate.

Download and store the private key

From the table of Active keys, download the private key file (.p8) and save it in a secure location. You can only download this file once, so store it carefully.

Save the Key ID

Find and save the Key ID in the same row as the key you just created.

Save the Issuer ID

Find and save the Issuer ID just above the list of Active keys.

Open Reports

Navigate to Reports, near the top center of the page. You can also reach it from the App Store Connect page by selecting Payments and Financial Reports.

Save your Vendor #

On the Reports page, save your Vendor #, listed at the top left. You now have everything from Apple you need to connect Recurly — stay logged in for one more Apple step below.

Configuration

Add the Apple source in Recurly

Navigate to App Management → App Connector. Under Apple App Store, select Add Source. If you're only replacing the API key, select View Details next to Apple App Store instead.

Input your key information

Enter the details you noted earlier. For Authentication Key, open the .p8 private key file in a text editor and paste the entire contents — including the hyphens and the BEGIN PRIVATE KEY and END PRIVATE KEY lines.

Replacing an existing keyIf you've already enabled the connection and are back to replace the API key, you only need to update the Authentication Key and Key ID fields. Once those are edited, the new key is in use and you can skip the remaining configuration steps.

Enable the connection

Ensure all four fields are populated and look similar to the example, then select Enable connection.

Copy the Production URL

Copy the Production URL shown on that page to your clipboard — you'll point Apple's notifications to it next.

Revenue-only setupIf you're only configuring App Management to push mobile app earnings into Recurly RevRec, you can stop here. Note that skipping the remaining steps means App Management won't provide visibility into your subscription lifecycles and related events.

Open your app in App Store Connect

Back in Apple App Store Connect, navigate to your app via My Apps, or from Apps at the top of the page.

Find App Store Server Notifications

In your app, go to App Store Server Notifications under General → App Information.

Set the Production Server URL

Next to Production Server URL, select Edit and paste the copied Recurly URL. Ensure Version 2 Notifications is selected, then select Save. If you're testing on a non-Production site, edit the Sandbox Server URL instead.

Confirm the URL in Recurly

Return to the open Recurly page and check the box confirming you've added the URL.

Complete configuration

Select Complete Configuration. Your Apple app is now connected to Recurly.

NoteThe "Last Notification Received" date stays blank until Recurly receives a valid notification from Apple. Test notifications sent directly from Apple App Store Connect won't affect this date.

Prerequisites

Before configuring Recurly App Management, create a new Google Cloud service account and API key with the right permissions.

Allow 36 hoursGoogle can take up to 36 hours to propagate service account access. Complete these prerequisites early and confirm at least 36 hours have passed before configuring App Management — your API access is checked during configuration to ensure subscriptions are tracked successfully.

Set up your developer and payments accounts

Ensure you have a Google Play Developer account and a profile in the Google Payments Center that's linked to your developer account. If your app isn't live yet, you can skip the payments profile and return to it before going live.

Configure Google Play Developer API access

Follow Google's instructions to link your developer account to a Google Cloud project, enable the Google Play Developer API, and set up a service account. See the details below.

Link your developer account to a new or existing Google Cloud project.
Enable the Google Play Developer API for that project.
Set up a service account with Google Play Console permissions to access the Google Play Developer API. When creating it, add the Pub/Sub Admin and Monitoring Viewer roles, and save the service account's email address.
Give the service account access to your app in Google Play Console: from Users and Permissions, select Invite new users, then Add app and choose your app. Under Account permissions, select View app information and download bulk reports (read-only), View financial data, orders, and cancellation survey responses, and Manage orders and subscriptions. Select Invite User to finish.

Create a JSON key

Follow Google's instructions to create a new JSON key for your service account. You can never recover this key from Google, so store it securely — you'll need it in Recurly.

Save the Earnings report URI

Using the "Find your Google Cloud Storage URI" section of these Google instructions, save the Google Storage URI that points to the Earnings report. Stay logged into Google Play and Google Cloud for the steps below.

Configuration

Wait for propagationConfirm at least 36 hours have passed since you created the JSON key before continuing.

Add the Google source in Recurly

In Recurly, navigate to App Management → App Connector and select Add Source for Google Play Store.

Input your credentials

Enter your service account JSON key, Earnings report URI, and app package name (details below), then select Verify Credentials. Once enabled, a Production URL is created — leave this page open.

JSON key: copy the entire contents of the JSON key file and paste them into the field.
Google Earnings Report URI: paste the full URI you saved earlier. It typically begins with gs:// and ends with earnings/.
App package name: in Google Play Console, open your app from Home to reach its Dashboard. Copy the unique package name shown directly under your app's name.

Set up Google Pub/Sub

Pub/Sub is how Recurly receives notifications from Google about subscription activity. Follow the sub-steps below to configure it.

Revenue-only setupIf you're only configuring App Management to push mobile app earnings into Recurly RevRec, you can skip the Pub/Sub setup and the remaining steps. Note that skipping them means App Management won't provide visibility into your subscription lifecycles and related events.

Following Google's instructions, create a topic. Uncheck "Add a default subscription" — you'll create one next.

While viewing the topic, save the Topic ID for later. Use the longer URI version — for example, projects/PROJECT_ID/topics/TOPIC_NAME — not just the name you provided.
Add a subscription to the topic by selecting Create Subscription within it, using the settings below.

Set the delivery type to Push and paste the URL from Recurly App Management into Endpoint URL.

Change the acknowledgement deadline from the default to 60 seconds.

Change the retry policy to "Retry after exponential backoff delay," keeping the defaults of 10 seconds minimum backoff and 600 seconds maximum backoff. Then select Create.

Following Google's instructions, grant Google Play privileges to publish notifications to your topic.

Enable real-time notifications

Following Google's instructions, enable real-time notifications for your app by inputting the topic name and sending a test message. Use the longer URI version of your topic that you saved earlier.

Complete configuration in Recurly

Return to Recurly, check the box confirming you've completed the Google configuration, then select Complete Configuration.

NoteApp Management is now set up for Google Play. The "Last Notification Received" date stays blank until Recurly receives a valid notification from Google.

Configure App Management

Once your mobile apps are connected, complete the configuration below.

Creating external products

External products let Recurly associate your unique Apple and Google subscriptions with a single product in Recurly — so you can track one subscription type whether it's sold on the web or your mobile apps. You only need to do this once per subscription you've created in Apple or Google.

Open External Products

Navigate to App Management → External Products in the left-hand navigation.

Create a new external product

Select New External Product.

Name it

Give the external product a name, such as Monthly Gold Plan.

Map a Recurly plan

Select the Recurly plan you want to map to this external product, such as Monthly Gold Plan - Web.

Add your source and reference code

Select Add Source to map your Apple or Google product, then enter the External Reference Code (details below).

Apple: provide the Apple Product ID of the product you want to map. You'll find it when viewing the details of a specific subscription in Apple App Store Connect.
Google Play: a subscription can have one or more plans, so you need both the Product ID and Base Plan ID. For example, with a Product ID of "ACME" and a Base Plan ID of "Monthly_Pass," you'd enter ACME+Monthly_Pass as the External Reference Code. In Google Play Console, go to Monetize → Products → Subscriptions; the Product ID is on the subscription's details view, and the Base Plan ID is in the first column of the "Base plans and offers" table.

Repeat for the other store

If you offer the same subscription via the other app store, repeat the previous step.

Save

Select Create External Product to save your changes.

For each subscription offered via Apple or Google, you should end up with one external product in Recurly. For example, if you offer a monthly and a yearly subscription, you'll have two external products when done. The example below shows three subscription offerings identified as external products.

Entitlements

Entitlements give you an easy way to control and grant access to features within your mobile app. When you create an entitlement, you'll see an option to assign an external product — that's how you connect one of the external products you just created. For full details, see the entitlements feature docs.

If you plan to use entitlements, navigate to Configuration → Entitlements and follow the linked instructions. The example below shows three entitlements configured.

Minimum setup completeYou've now completed the minimum requirements to get App Management working properly. If you need to migrate historical subscription activity, see the Migration section below.

Webhooks

Once Recurly processes a real-time notification from Apple or Google and updates the subscription data, it can send a webhook notification specific to the subscription event — for example, subscriber canceled. To receive those webhooks, see configuring Recurly to send webhooks.

Migration

Due to limitations with the Apple and Google App Stores, Recurly can't automatically ingest historical data from the app stores on your behalf. This includes any app store subscriptions created before you started using Recurly App Management. To reflect that data in Recurly, you'll need to backfill our records with the subscription and customer information stored on your side.

This backfill process can be performed using Recurly's API. If you'd like help, the Professional Services team can either guide you through using the API or perform the import on your behalf. Contact the support team to request a paid engagement with the Professional Services team.

Updated 14 days ago

Did this page help you?