Meta Install Referrer

Definition

The Meta Install Referrer is an encrypted campaign payload that Meta places in the Google Play install referrer string, allowing an advertiser's Android app to decrypt deterministic attribution data for installs driven by Facebook and Instagram ads.

It solves a specific problem: Meta will not publish campaign identifiers in a plaintext referrer that any party could read, but advertisers legitimately need deterministic attribution for their own installs. The compromise is that the data rides in the standard Play install referrer, encrypted with a key only the advertiser holds. Decrypt it and you get click-through versus view-through, campaign, ad set and ad IDs, and a trustworthy click timestamp.

What arrives, and where

There is no separate API. You read the ordinary Play install referrer, and if the install came from a Meta ad the string contains a utm_content value holding a small JSON object.

{
  "source": "apps.facebook.com",
  "data": "1f3a9c...",
  "nonce": "9b2e7d41c0a5..."
}

Decrypting it

The key is per-app and comes from Meta's app dashboard, under the app's install referrer settings. It is a secret: it belongs on your server, not compiled into the APK where anyone can extract it.

import javax.crypto.Cipher
import javax.crypto.spec.GCMParameterSpec
import javax.crypto.spec.SecretKeySpec

fun decryptMetaReferrer(dataHex: String, nonceHex: String, keyHex: String): String {
    val cipher = Cipher.getInstance("AES/GCM/NoPadding")
    cipher.init(
        Cipher.DECRYPT_MODE,
        SecretKeySpec(keyHex.hexToByteArray(), "AES"),
        // 128-bit auth tag; the tag is appended to the ciphertext in `data`.
        GCMParameterSpec(128, nonceHex.hexToByteArray())
    )
    return String(cipher.doFinal(dataHex.hexToByteArray()))
}

private fun String.hexToByteArray(): ByteArray =
    chunked(2).map { it.toInt(16).toByte() }.toByteArray()

{
  "ad_id": "23851234567890123",
  "adset_id": "23851234567890000",
  "campaign_id": "23851234560000000",
  "campaign_group_id": "23851234500000000",
  "publisher_platform": "facebook",
  "is_ct": true,
  "actual_timestamp": 1755500000
}

Where this fits against the alternatives

The referrer's advantage over the dashboard is not accuracy but independence: it is the same event, recorded in your own infrastructure, which is what lets you audit a self-attributing network rather than accept its claims. Discrepancies then become answerable questions rather than a negotiation.

1. Enable the install referrer for your app in Meta's dashboard and copy the decryption key into your server's secret store.
2. Read the Play install referrer on first launch and forward the raw string to your server without parsing it on-device.
3. Server-side, check source, decrypt, and store the raw ciphertext alongside the decrypted result so a key rotation or parsing change is replayable.
4. Reconcile against Meta's dashboard weekly, segmented by is_ct. Persistent gaps in one direction point at instrumentation, not at Meta.
5. Keep a non-Meta path in the same pipeline, since your own dl_id links flow through the identical referrer field.