Connect RevenueCat
Connect your RevenueCat project so Tapper Vantage learns the value of each subscription, from the first payment to every renewal and refund, read-only.
RevenueCat is where many app teams manage subscriptions for the App Store, Google Play and the web. Connecting it lets Tapper read your subscriptions, so Vantage learns what each subscriber is worth after store commission, tax and refunds. To learn more about Vantage, see Tapper Vantage.
Tapper only reads. The secret key you create has read permissions and nothing else, and every request Tapper makes to RevenueCat is a read. Tapper never creates or changes anything in your RevenueCat project.
One connection covers every app in a RevenueCat project, iOS, Android and web alike. A RevenueCat project Admin does the RevenueCat steps once for the whole project.
How the connection works
They start a trial or pay, on the App Store, Google Play or the web. RevenueCat records the transaction.
A webhook delivers each event to Tapper as it happens. Tapper checks the authorization value on every delivery, and the signature too when you turn signing on and give Tapper the signing secret.
RevenueCat writes its transactions to a Google Cloud Storage bucket you own. Tapper reads every transactions file in it, oldest first, so your history comes in, and each later file adds new and changed transactions, including refunds of earlier periods.
Tapper keeps one row per store transaction, with the price, the tax, the store commission and the refunds. The email and phone number are hashed the moment they arrive, and other personal fields are dropped.
The two routes do different jobs. The webhook gives speed: Tapper hears about a trial, a payment or a cancellation as it happens. The export gives completeness: it covers your history from before you connected, any event a webhook did not deliver, and refunds of earlier periods, which RevenueCat sends no webhook for.
If you do not set up the export, the connection still works from the day you switch it on. The history from before that day is not read.
Before you start
- In RevenueCat, you need a role that can create API keys and add webhooks in the project you want to connect.
- In Tapper, you need the Owner or Admin role, with two-step sign-in, to connect, test, change or disconnect RevenueCat.
- For the history export, you need a Google Cloud Storage bucket that you own.
Make a read-only secret key
Do this in RevenueCat.
Open the project you want to connect, then Project settings and API keys.
Create a secret key and choose version V2. Name it Tapper.
Give the key read permission on exactly these nine, and nothing that can write.
Copy the key. It starts with sk_.
| Group | Permissions to set to read |
|---|---|
| Customer information | Customers, subscriptions, purchases and invoices. |
| Project configuration | Projects, apps, products, entitlements and integrations. |
Tapper reads your project from the key, so you never type a project id. The key must belong to one project.
Connect from Tapper
In Tapper, open Setup > Data sources in the sidebar. If your workspace has more than one entity, first pick the one your app belongs to in the entity switcher at the top of the sidebar. Click Add source, open the Payments group and choose RevenueCat.
Click Set up. In the Connect RevenueCat dialog, paste the secret key into Secret key. Tapper stores it encrypted and never shows it again.
If you switch on signing for the webhook in RevenueCat, paste its signing secret into Webhook signing secret (optional). Leave it empty if you do not. You can set or change it later on the Settings tab.
Click Connect. Tapper saves the connection switched off, and shows a notice with the webhook Authorization value.
Click Copy, paste the value somewhere safe for the next step, then click I have copied it. Tapper keeps only a scrambled copy, so it cannot show the value again. If you lose it, open the Settings tab and click New webhook value: the old value stops working at once.
Enter the key in Tapper only, never by email or chat.
Add the webhook in RevenueCat
The webhook address is on the Settings tab of the RevenueCat page in Tapper.
In RevenueCat, open Integrations, then Webhooks, and add a new webhook. Name it Tapper.
Paste the webhook address from Tapper as the webhook URL, and the Authorization value as the Authorization header value, exactly as shown.
Send events from production, for all apps in the project, with no event filter.
If you turn on signing, copy the signing secret that RevenueCat shows and paste it into Webhook signing secret on the Settings tab in Tapper. It must match the one in RevenueCat.
Press the test button on the webhook in RevenueCat. Tapper shows the time it arrived under Last test event on the Overview tab.
Export your history
The history export lets Tapper read what happened before the webhook, and every refund of an earlier period. RevenueCat writes it to a Google Cloud Storage bucket you own, and Tapper reads that bucket with an account made for your connection alone. Set where RevenueCat exports on the Settings tab, under Where RevenueCat exports.
Set the export in RevenueCat to the Transactions feed, in CSV, daily, with new and updated transactions only, and with every column selected. Tapper reads CSV files only, and a file that lacks a column Tapper needs stops the read until the columns are fixed.
In Google Cloud, create a storage bucket for the export, or choose an existing one.
In RevenueCat, open Integrations, then the scheduled data export for Google Cloud Storage, and point it at that bucket.
In Tapper, open the Settings tab and choose Google Cloud Storage under Where RevenueCat exports. Enter the bucket name only, without gs://, and the folder if RevenueCat writes into one. Click Save location.
Tapper shows an account address under Give this account access. In Google Cloud, give that account the role Storage Object Viewer on the bucket, and on the bucket only.
Tapper reads the export every hour and keeps its place, so each new file is read once. Delete location on the Settings tab stops the history read and leaves the webhook running.
Test and switch on
On the RevenueCat page in Tapper, click Test connection. Tapper checks six things and reports each one in plain words: Secret key, Read permissions, Webhook, Signing secret, Test event and History export.
A failed step says what to fix. The table below lists the common ones. Test again after each fix.
After a test that passes, click Switch on, then confirm. Tapper starts reading new events through the webhook and the history from the export.
The Switch on button waits for a passing test of the values stored now. If you change the key, the signing secret or the webhook value, Tapper switches the connection off and asks for a new test before it reads again.
| What the test says | What to do |
|---|---|
| RevenueCat did not accept the secret key. | Create a V2 secret key in this project and enter it again with Replace key. |
| The key is missing a read permission. | Tick every permission listed on this page on the key in RevenueCat, then test again. |
| This key can see more than one RevenueCat project. | Create a key in the one project you want to connect. |
| No webhook points at this connection's address. | Add the webhook with the address and the Authorization value Tapper showed you. |
| The webhook sends sandbox events only. | Set it to production in RevenueCat. |
| The webhook covers one app and this project has more. | Set it to all apps in RevenueCat. |
| Tapper cannot read the history export folder. | Open the History export step of the test for the reason, and see the next table. |
| RevenueCat asked Tapper to slow down. | Try again in a minute. |
The History export step names what to fix when the bucket cannot be read.
| What the test says | What to do |
|---|---|
| Tapper cannot find that bucket. | Check the bucket name. |
| This connection's read-only account cannot read the bucket. | Give the account the Storage Object Viewer role on the bucket, then test again. |
| A file in the export could not be read. | Set RevenueCat to export CSV files. |
| A file in the export lacks a column Tapper needs. | Check the column selection of the export in RevenueCat and select every column. |
| There are too many files under this folder. | Choose a narrower folder. |
Where the connection stands
The RevenueCat page has three tabs.
- Overview shows whether Tapper is reading the project, the project read from the key, the masked key and signing secret, the last event, the last test event and the state of the history export. The Test connection, Switch on, Switch off and Disconnect buttons sit at the top of the page.
- Settings holds the webhook address, New webhook value, the export location, Replace key and the signing secret.
- Activity shows the last test and what it checked.
Switch off stops Tapper reading the project. What it already read stays, and the connection and its keys stay, so you can switch it on again.
What Tapper reads
| Data | How Tapper keeps it |
|---|---|
| Transactions: store, product, dates, renewal and trial flags. | As it is. |
| Price in your currency and in USD, tax and store commission. | As it is, with what you keep worked out from them. |
| Refunds, cancellations, billing issues and expiries. | As it is. |
| App user id and aliases. | As it is. |
| Attribution ids and campaign names that your app sets. | As it is, after a shape check. |
| Ad click ids and UTM parameters on web purchases. | As it is. |
| Email and phone number. | Only as a SHA-256 hash, made on arrival. |
| IP address, display name and any other custom attribute. | Dropped on arrival. Not stored. |
| Sandbox and test store purchases. | Dropped on arrival. Not stored. |
The key and the signing secret are encrypted when you save them and never shown again. The webhook Authorization value is stored only as a salted hash.
Lifecycle stages
Tapper files every RevenueCat event under one stage, named for the subscription.
| Stage | From RevenueCat |
|---|---|
| Trial started | A first purchase in a trial period, or in a free intro period. |
| First payment | A first purchase at a paid price, or a renewal that converts a trial. |
| Renewal | Any other renewal. |
| One-off purchase | A purchase that does not renew. |
| Refund | A negative price, or a cancellation for a refund. |
| Refund reversed | A refund the store took back. |
| Auto-renew off | Any other cancellation. |
| Auto-renew back on | An uncancellation. |
| Billing problem | A failed charge. |
| Ended | An expiry. |
| Plan change | A product change. |
| Moved to another user | A transfer of a subscription between subscribers. |
| Paused | A paused subscription. |
Turn it off
- In RevenueCat, delete the secret key and the Tapper webhook, and remove Tapper's access to your bucket. Each stops that part at once.
- In Tapper, open the RevenueCat page and click Disconnect. Tapper stops reading, deletes the stored key and signing secret, and deletes the account it made for your bucket. The history already read stays in Tapper.
- To have one subscriber's data, or all of a project's data, erased, contact support.