How to Decrypt the Meta Install Referrer on Android
Facebook and Instagram can tell your app which campaign, ad set and ad brought an install, views included. The data is encrypted with a key only you have.
The Google Play Install Referrer only carries Meta ad taps that install in the same session. The Meta Install Referrer covers the rest: the Facebook, Instagram and Facebook Lite apps keep the ad your user saw or tapped and hand it to your app.
Play Install Referrer
- Same-session taps
- Encrypted Meta data
- Also carries Google Ads clicks
Meta Install Referrer
- Taps, views and earlier sessions
- Same encryption, same key
- Tells you tap or view
Before you start
An Android app-install campaign
On Facebook, Instagram or Audience Network.
Your Facebook App ID
The one your ads run under.
The decryption key
Meta for Developers › App settings › Basic › Android. Admin access needed.
1. Read it on first launch
AndroidManifest.xml
<queries>
<package android:name="com.facebook.katana" />
<package android:name="com.instagram.android" />
<package android:name="com.facebook.lite" />
</queries>Kotlin
val providers = listOf(
"com.facebook.katana.provider.InstallReferrerProvider",
"com.instagram.contentprovider.InstallReferrerProvider",
"com.facebook.lite.provider.InstallReferrerProvider",
)
fun readMetaReferrer(context: Context, facebookAppId: String): String? {
for (authority in providers) {
val uri = Uri.parse("content://$authority/$facebookAppId")
runCatching { context.contentResolver.query(uri, null, null, null, null) }
.getOrNull()?.use { cursor ->
if (cursor.moveToFirst()) {
return cursor.getString(cursor.getColumnIndexOrThrow("install_referrer"))
}
}
}
return null
}2. Decrypt it on your server
Never ship the key in your app. Anyone who unpacks the APK could read it.
Node.js
import crypto from 'node:crypto';
export function decryptMetaReferrer(installReferrer, keyHex) {
const {utm_content} = JSON.parse(installReferrer);
const {source} = typeof utm_content === 'string' ? JSON.parse(utm_content) : utm_content;
const sealed = Buffer.from(source.data, 'hex');
const decipher = crypto.createDecipheriv('aes-256-gcm', Buffer.from(keyHex, 'hex'), Buffer.from(source.nonce, 'hex'));
decipher.setAuthTag(sealed.subarray(-16));
return JSON.parse(Buffer.concat([decipher.update(sealed.subarray(0, -16)), decipher.final()]).toString());
}The field names are one level off
campaign_groupcampaignadgroup
campaign_group
Campaign
What Ads Manager calls the campaign.
campaign
Ad set
Not the campaign.
adgroup
Ad
The creative people saw.
When it comes back empty
With Appy, paste the key once
On the Enterprise plan you add the key in the dashboard and your App ID in the SDK. Decryption happens on Appy’s servers.
First launch
Android, Appy SDK
- Tapped your Appy linkCredited to the link
- Meta ad, tap or viewCampaign, ad set, ad
- Google Ads clickCredited to Google Ads
- None of theseOrganic
Read next
Questions
Where is the decryption key?
Meta for Developers, App settings › Basic, in the Android section.
Which encryption does Meta use?
AES-256-GCM with a 64-character hex key.
Does it include view-through installs?
Yes. The is_ct column is 0 for a view and 1 for a tap.
Is campaign_name the campaign?
No, it is the ad set. The campaign is campaign_group_name.
Continue exploring
Deferred Deep Linking Without an SDK: How It Actually Works Under the Hood
You can carry link intent across an app install without embedding an attribution SDK. What actually survives the store boundary on Android and iOS, what breaks, and what each workaround costs in privacy.
Know Which Link Brought Every Install: Appy’s iOS and Android SDK
Appy now follows your links past the app store: installs, in-app events and revenue for every link, QR code and campaign, and new users who open on the right screen.
Chrome Tells Every Server Your Phone Runs Android 10
Chrome on Android reports every phone as Android 10, model K. What that did to deferred deep link matching, why Critical-CH would count every click twice, and how Client Hints bring the real version and model back.
Looking for something else? Browse all topics on the blog.
Meta installs next to every link and QR code
Paste your key once and Appy credits Facebook and Instagram installs to the campaign, ad set and ad.