How to use Qonversion inside Hybrid applications using CapacitorJS

Foreword

Hopefully this helps a few people out with billing options inside a hybrid application. It's purpose is to provide an overview of setup, implementation and testing of Google Play Subscriptions within Hybrid Applications. No hidden marketing agenda here, I solve problems and this is the way I solved this one.

1.0 The Play Store and the Developer Console
2.0 How does the Free trial actually work?
3.0 Subscriptions and Authentication
4.0 Setup and Implementation
4.1 Installing my Capacitor Plugin (NPM coming soon)
5.0 Testing
6.0 Resources

1.0 The Play Store and the Developer Console

Most of the Play Store is self explanatory, however there are a few key things I'd like to point out when publishing an application.

The Price set for a subscription does NOT include the local country tax.
The "App Pricing" section of the Play Store is where the default one-off price is set. This must be set to FREE if using subscriptions. (The scary bit I know)
Setting your application to FREE cannot be undone. So please to absolutely sure this is route you want your application to go down.
A potentially obvious one but still - Subscriptions require the installation of the android billing library.
If the android billing library is installed and the application has NOT been set to FREE then the user would have to pay the initial price to download the app and then the subscription price on top of that to access the locked features of the application.
You can mix and match default pricing + subscriptions to handle various situations that might be required for your app. It's all just a case of how you handle the logic inside the app.
A caution about Tax and Compliance. I suggest you read through this Google Answer to get a feel for some of the compliance questions you will have to answer. A couple of big ones will be:
- Is your app a streaming service? (If distributed in the U.S.)
- Is your app a Service or Digital Content? (If distributed in European Economic Area EEA)
Background reading and lifecycle events

2.0 How does the Free trial actually work?

You may wish to add a free trial to your application. There is a bit of configuration required in the play store, in the Products section but that's straight forward.

If you have a free trial setup on a product then the user has to "purchase" the application first. This "purchase" is charged at $0.00 which allows the user to enter the free trial phase of the subscription. Then, at the end of the free trial the user is automatically charged the subscription cost.
Users who cancel their subscription before the end of the free trial will not get charged.
Users can encounter a billing issue due to something like a credit card expiring. Please bare this in mind when locking features / sections of your application. You will also need to think about how best to present your users with the fact there was a billing issue.

3.0 Subscriptions and Authentication

Here is a friendly note from Googles Documentation and a couple of key points when considering payment integration for Android Apps.

As part of integrating Google Play's billing system into your app, we strongly recommend that you use a secure backend server to implement billing-related tasks such as purchase verification, subscription-specific features, and handling Real-time developer notifications.

In order to protect your application and your app store data is it highly recommended to use a Purchase Authentication Server. Now, if you're just testing then you don't need one and testing connections / features this way is fine, just be aware that it will most likely need to change.
This is where Qonversion comes in, they provide this Purchase Authentication Server for FREE. There's more good news, not only do Qonverion have the server side covered but they also provide a variety of SDK's and plugins which connect to the server.
There are a few solutions out there that offer similar / the same services and you can even create the Purchase Authentication Server yourself, but you know it's free so.
At the time of writing this, there is currently no way to remove a subscription from the play store. They can be activated / deactivated, just be sure when testing that you set the locking / unlocking of features to its corresponding subscription.

4.0 Setup and Implementation

This is where we discuss the fun stuff and hopefully I've done a good enough job of explaining it. Qonversion overview

Setup the connection between Qonversion and the Developer Play Store. Qonversion write a good guide on this.
Bare in mind in can take a couple days for the connection to be made and products / subscriptions to be fetched from Google.
You'll need to setup Products, Offerings and Permissions within the admin Qonversion portal. Keeping everything named the same will save you a lot of hassle. You wanna be looking at the Product ID in the Developer Play Console, not the name.
Once the connection has been established then you can install the Qonversion SDK into your application. This is where things differ depending on platform / codebase. Installing the SDK's is where you need to go in order to install for a bunch Android / iOS / React Native etc. However if you want CapacitorJS then read on.

I've been pestering Qonversion with my questions regarding their publicly available code bases until I have been able to grow my understanding and create my own plugin for CapacitorJS which allows developers the ability to install the Android Billing Library and create subscriptions for their hybrid applications. Qonversion do offer this for Cordova as well. The code is public and available at: Capacitor Plugin Qonversion Code. There are some updates that are required and I'm working with the Qonversion team to improve the offerings / versions available based on the Android Billing Library Versions. Once these updates have been made then I will be able to submit it to CapacitorJS as an npm package for better consumption.

4.1 Installing my Capacitor Plugin (NPM coming soon)

When I use the terms locked and unlocked I mean refusing / allowing access to application features, respectively.

Copy the repo into the root directory of your Capacitor Project so it looks like: /capacitor-plugin-qonversion.
- Update dependencies inside package.json => "capacitor-plugin-qonversion": "file:capacitor-plugin-qonversion",
- Then you can run npm i

Import and use in a file, all public methods are described in the repo.

import { QonversionPlugin } from 'capacitor-plugin-qonversion';
QonversionPlugin.launchWithKey({
 key: process.env.VUE_APP_QONVERSION_KEY,
 observerMode: false,
}).then((response) => {
 console.log('actionBillingInitialise SUCCESS:::', JSON.stringify(response));
}).catch((error) => {
 console.log('actionBillingInitialise ERROR:::', error);
});

Then you're good to go. Once the connection and launchWithKey works as expected then you can fetch offerings, products, subscription status, free trial status and make purchases. And from here you can lock / unlock features based on what is returned from these calls. The general flow is as follows, in order:

NB: Best to lock features by default and then update with unlock after making the appropriate calls / checks.

On app load, Initialise billing with launchWithKey
On app load, fetch the offerings upon success of launchWithKey
On app load, check the subscription status of the user checkPermissions.
Inside the checkPermissions call - If no products get returned then the user is not subscribed then you can lock the corresponding features of your application and present a paywall.
Inside the checkPermissions call - If products do get returned then you can unlock features based on the renew_state and isActive. The current options for the renew_state are below (at the time of writing). Each of these states will need to be accounted for when considering if the features should be locked or unlocked.
- WillRenew
- NonRenewable
- BillingIssue
- Canceled
Create a paywall (basically a popup which shows the user a subscription and that they must pay to access this features / content google docs)
Create a place to present the users subscription(s) statuses and where they can update them if required. (Usually somewhere in settings)
Toasts or small popup messages can also be presented to the user to display how long they have left on the free trial.
A variation on the paywall could be presented to the user if they are still in the free trial period, asking them to purchase the subscription - rather than waiting for the free trial to end.

There are various situations and reasons for presenting or not presenting things like a paywall to your users. At this stage it's all about how best to improve conversion rates and thus revenue.

5.0 Testing

A couple of caveats about testing and an idea on how to approach it.

(At the time of writing, updates may follow) It is important to setup multiple subscriptions within the Developer Play Console. This is because even in testing free trials are a one-off and cannot be reset once the free trial has been granted, even with developer / test accounts. Therefore multiple subscriptions must be setup to test multiple times, ensuring that the implementation of the Android Billing Library within your application covers all the required use cases. Things like the locking of routes and features to only those that have the free trial and how the transition from free trial to paid subscription works or billing issues - the list goes on.
Add test accounts to your Developer Play Console so you can run tests via the Android Emulator. Once a user has accepted being a tester then they will be provided test cards (from Google) that can emulate the success / failure of a purchase. These test accounts will also show a reduced free trial time, so you don't have to wait a week to see what happens when a free trial converts to paid or not. E.g. 7 day free trial would equate to a 5 minute free trial.
If you have already launched your application without billing - this is fine, just install everything you need and configure everything you need. However you will need to take into account if a user has paid the default one-off payment we spoke about earlier. So instead of looking at subscriptions within the applications payment logic, you'll need to look at the one-off payments.

6.0 Resources

Me

All of the above I've actually implemented in my own application, and learning the lessons I have, I wanted to share that with you.
If you want to see how it works in action or you are interested in learning poker give it a download My Live Poker. It's not a game app its a tracking and management application.

Hopefully you found this helpful and thank you for reading.

Android Billing tl;dr (Subscriptions + Hybrid Applications)