In App Purchases

Offer access to premium content to subscribers only

Shoutem supports only auto-renewable subscriptions that can unlock one or more specific screens in your app, or all screens combined. With that being said, there are a few key points that you should keep in mind before you proceed with this setup:

1. You cannot restrict specific items only on your screen, but the content of that screen as a whole.
2. Only a one-tier subscription is supported, meaning that you can offer only one subscription price that will renew on a weekly/monthly/yearly basis.
3. Created subscription must be auto-renewable – other types are not supported and you cannot combine it with other subscription types.

In this article, we will first guide you through the In-App purchases setup process for newly created apps (apps that are not already available in the app stores). Later on, we will mention where to start if your app is already live in the stores, how to test this feature without being charged, and how to remove it.

NOTE: DON’T GET IT CONFUSED – THIS FEATURE HAS A DIFFERENT NAME IN THE STORES – IT IS CALLED “SUBSCRIPTIONS“.

Newly created apps that require IAP setup

Prerequisites:

1. Make sure that we have access to your Google Play Console and App Store Connect accounts.
2. Create IAPHUB account.
3. Enter Store metadata of your app.

1. INSTAL IN-APP PURCHASES EXTENSION

The first step into this setup is to install the In App purchases extension to your app. In the Extensions tab, click on the + symbol from where the Extension marketplace window will be opened and search forIn App Purchases to install it by clicking INSTALL.

This particular feature doesn’t have any additional screens that should be managed in the Screens tab in the builder so the whole setup will be managed in the Settings tab → In App Purchases.

IAP SETTINGS HAVE THE FOLLOWING SECTIONS:

• GENERAL – here you can enable or disable the feature and add keys and IDs that are required. Fill in this page after our part is done (see the next steps)!!!
• SUBSCRIPTION RESTRICTIONS – a section where you can select the screens that will be restricted with the auto-renewable subscription.
• PRIVACY POLICY – the URL of your Privacy Policy which will be visible on the subscription screen.
• TERMS OF SERVICE – the URL of your Terms of Service which will be visible on the subscription screen; needs to include the title of the auto-renewing subscription, which may be the same as the in-app product name, length of subscription, and the price of the subscription.
• SUBSCRIPTION SCREEN – a section where you need to add details of a pop-up page that will be displayed as the user enters the restricted screen (only in situations where the app doesn’t have an active subscription status).

For now, make sure that every section of this extension, apart from GENERAL, is filled in.

2. PUBLISH YOUR APP AND LET US DO OUR PART

Once you have published your app, make sure that you contact our Support team right away so that we can do our part. We will create an app on your Google Play Console account and App Store Connect (but the app won’t be submitted to stores just yet!) so that you can complete the setup in the stores and IAPHUB.

3. APP STORE CONNECT IAP SETUP

We have created your app on App Store Connect – now what?

To be able to create an auto-renewable subscription, you should first accept Paid Apps agreement in the Agreements, Tax, and Banking tab of App Store Connect. Status needs to be set to Active, because otherwise, your IAP for iOS app won’t work.

Once this is done, navigate back to Apps tab and find your app. Under FEATURES you’ll see a tab called Subscriptions.

Here are the steps on how to create your auto-renewable subscription:

1. Create a Subscription group by clicking on the CREATE button – the reference name of this group is up to you

2. A new settings page will open where you’ll create a Subscription – click on the CREATE button under Subscriptions and enter the Reference Name as well as the Product ID of your choice

3. On this page, you will insert the mandatory pieces of information regarding your subscription, such as subscription duration, price, localization, etc.

• Subscription Duration – subscription can be set to renew every week, month, 2 months, 3 months, 6 months or every year – use the same billing period for both stores!

• Subscription Prices – you can select a price from a dropdown menu, defined by Apple

• Introductory Offer is where you can set up a free trial – you will be offered to set up its availability, select if it is free or paid and how long it will be available for all new users

• Offer codes and Promotional Offers are not mandatory for the IAP set-up, but you can use these options when you find them suitable (skip to How to subscribe to your app free of charge to learn how to create and redeem promo codes)
• App Store Localization – add a display name and description for your subscription that will be visible on the App Store (if you have an app in many different languages, you should consider localizing the subscription to all languages that you offer)

• App Store Promotion is not something that we support at the moment so this can be skipped
• Review Information – add review notes (a description of what your subscription will unlock) and we’ll add a screenshot before the submission of your app (this will be visible to Apple’s review team only so that they can understand how your subscription works)

4. Save your subscription by clicking on the Save button in the upper right corner

5. App Store Localization outside of the subscription is mandatory as well – all you need is the name of your reference group that will be visible to the users when they manage subscriptions on their devices

For a more detailed clarification of each section in the Subscriptions, please visit the official support page by Apple.

After you have completed the IAP product setup, you will need to generate App-Specific Shared Key which you will use for the IAPHUB setup. Here is how to do it:

Once you are done with the App Store Connect flow, do not close this window just yet as you will need your generated Shared Secret Key and Product ID for IAPHUB and the settings in the builder.

4. GOOGLE PLAY IAP SETUP

We have created your app on Google Play Console and you have completed App Store IAP setup – now what?

Before you start, make sure that you have a Google Payments merchant account – you will need to configure Google Play API by completing the steps from the tutorial provided by IAPHUB on their official Documentation page SET UP ANDROID (Step 4 can be completed later!). This API is needed so that your app can communicate with IAPHUB and Google Play.

In the Google Play Console, open your app → navigate to Monetize → choose Subscription → click Create subscription. From there, you will need to add the following:

1. Product ID of your choice (you can use the desired combination of letters and characters, eg. androidsub123) and the name of the subscription

2. Base plan (where you’ll set prices, base plan ID and tags, as well as define the renewal type)

The billing period can be set to weekly renewal, every 4 weeks, monthly, every 3 months, every 6 months, or yearly – use the same billing period for both stores!

Once you’ve completed the base plan settings, click Activate.

3. If you’d like to add an offer such as a free trial, go back to the main menu and choose Add offer

Once you’ve finished with phases, activate your offer.

For a more detailed clarification of each section in the Subscriptions, please visit Google’s official support page.

Memorize your Android Product ID since you will use it for the IAPHUB setup, as well as the setup in the builder.

5. IAPHUB SETUP

As one of the IAPHUB partners, we are proud to offer IAPHUB integration which you will use for managing your IAP, see a general overview of current, cancelled, and renewed subscriptions, add listings, etc. IAPHUB subscription needs to be activated because the free version supports only Sandbox purchases. Make sure to review their pricing plan on this link.

The tutorial on how to complete the setup can be found on their SET UP APP page. Upon registration, you will be required to create an app by entering the app’s Name, your Currency and Time zone.

Once the app is created, follow these steps to complete the setup:

1. Go to Settings and set up the Android app as explained here in Step 4 (you will need the JSON key from Step 4 – GOOGLE PLAY IAP SETUP of this article). Bundle ID can be found in the App Info tab in the builder.

2. On the same page (Settings) set up iOS app as explained here. You will need App-Specific Shared Key from Step 3 – APP STORE CONNECT IAP SETUP of this article. Bundle ID can be found in App Info tab in the builder.

3. Open Products tab and create a product – you will need Product IDs for that (created by you in Steps 3 & 4). Details can be found here.

4. Add your product as a listing in Listings tab and activate it, as explained here.

That would be all from IAPHUB for now – don’t forget to activate their subscription!

6. SHOUTEM IAP EXTENSION CONFIGURATION

The last step in the whole setup is to finish the configuration in the builder. For that, you will need:

1. iOS and Android product ID (see Steps 3 & 4)
2. Client API key from IAPHUB
3. IAPHUB App ID from IAPHUB

As the last step, enable the subscription in-app screen and save settings.

Note – at least one Product ID and all IAPHUB settings must be added before you can save these settings!

7. CONTACT SUPPORT!

Here's an example of the subscription screen:

Existing apps that require IAP setup

The flow is pretty much the same, just start from STEP 3 and get back to us so that we can resubmit your app with this feature.

Additional IAP information:

IAP feature in the preview simulator

On Disclose, you will not see your price but Undefined value. Nothing to worry about, that is intended behaviour – your price will be visible once the app is approved and actually installed on your mobile device.

Free trial time

The free trial time will always be counted in days on your app – that is how the feature is developed. Also, your app users will not see the free trial time if it’s not available to them (i.e. when restoring subscription).

How to subscribe to your app free of charge

ANDROID

If you are logged in Google Play Store with an email that is added as a licence test user for the app in question, you will not be charged for purchasing the subscription. As an owner of your Google Play developer account from where the app is submitted, you are automatically registered as a licenced tester and able to test the purchase on any Android device where you are signed in with the email associated with your GP developer account without being charged. For more information, see the official Google Play Support page.

You can also create Promo codes on Google Play Console. Find Promo codes in the Monetize section and insert the required pieces of information.

Your promotion will become active and you will be able to export the codes by clicking the download button. For more information, click here.

The promo code can be redeemed through Google Play Store – the user will need to go to their Google Play Store account → click Payments and subscriptions → choose Redeem a gift card or promo → insert one of the promo codes from the downloaded file → click Redeem. The user will then need to open the app, go to one of the restricted screens and choose Restore.

IOS

Create offer codes on your apps’s IAP in App Store Connect by clicking the plus button next to Subscription Prices. You will need to insert:

1. Offer Reference Name
2. Customer Eligibility
3. Introductory Offers
4. Countries and Regions for Offer
5. Type of offer
6. Duration of the offer

Once that is set, submit the offer by pressing the SUBMIT button.

Next, click on the Offer → click Create One-Time Use Codes → choose the number of codes to create and the expiration date → click Create and download the codes.

To redeem a code, the user needs to go to their Apple App Store account → choose Redeem Gift Card or Code → click “You can also enter your code manually” → insert one of the promo codes from the downloaded file > click Redeem. They will then need to open the app, go to one of the restricted screens, and choose Restore.

IAP can also be tested in TestFlight free of charge – the following message will be added to Details upon the purchase:

Remove IAP from your app

First things first, remove the IAP extension or disable the subscription screen from your app and make sure to reach out to your subscribers about the upcoming changes.

ANDROID

1. Go to Order management and cancel each active subscription manually – this way you would avoid them being billed upon the renewal
2. After cancelling all subscriptions, wait 1 subscription period (i.e., cancelling a monthly subscription on Jan 10th, you would need to wait until at least Feb 10th)
3. Once the subscription period has expired for all subscribers and no users are renewed, you may remove the content from the app.

IOS

1. Remove Availability → Cleared for Sale of your app’s IAP in App Store Connect
2. Save changes.

Once you have completed the steps for both iOS and Android and reached out to your users, get back to us so that we can resubmit your app without IAP.