Aggiungi un programma di affiliazione o referral alla tua app Android.

Passo 1: aggiungi gli artefatti che ti servono

L'SDK è diviso in tre artefatti su Maven Central, tutti alla stessa versione, quindi mavenCentral() deve essere tra i tuoi repository. Aggiungi solo ciò che ti serve: ogni componente aggiuntivo porta con sé il core, e gli artefatti core e billing includono le proprie regole R8/ProGuard.

// build.gradle.kts
dependencies {
    implementation("to.influ:android-sdk:1.1.1")
    // optional: Compose code field (InfluToReferralCodeInput)
    implementation("to.influ:android-sdk-ui:1.1.1")
    // optional: store-direct purchase auto-capture
    implementation("to.influ:android-sdk-billing:1.1.1")
}

Passo 2: inizializza in Application.onCreate

initialize è una funzione suspend. Chiamala una volta all'avvio e attendila: finché non va a buon fine, checkAttribution e reportPurchase lanciano InfluToError.NotInitialized. Se fallisce (chiave sbagliata, nessuna rete) lancia un'eccezione: intercettala, registrala e vai avanti.

Usa Application.onCreate o uno scope valido per tutta l'app, non l'onCreate di un'activity, che viene rieseguito a ogni cambio di configurazione. Non sei in una coroutine? Ogni metodo di rete ha un overload con callback; i callback girano su un thread in background, quindi passa al thread principale prima di toccare la UI.

La chiave API (it_…, in Setup & SDK) vale sia per lo sviluppo sia per la produzione. Tienila in un campo BuildConfig valorizzato da una proprietà Gradle in local.properties o dai segreti della tua CI. Un avvio tipico in un'app con RevenueCat:

class MyApp : Application() {
    private val appScope = MainScope()

    override fun onCreate() {
        super.onCreate()
        // RevenueCat apps: configure it first
        Purchases.configure(PurchasesConfiguration.Builder(this, "goog_…").build())

        appScope.launch {
            try {
                InfluTo.initialize(this@MyApp, InfluToConfig(
                    apiKey = BuildConfig.INFLUTO_API_KEY,
                    appVersion = BuildConfig.VERSION_NAME,
                ))
            } catch (e: Exception) {
                Log.w("InfluTo", "initialize failed", e) // retried on the next launch
                return@launch
            }
            val attribution = InfluTo.checkAttribution()
            InfluTo.identifyUser(Purchases.sharedInstance.appUserID)
        }
    }
}

Passo 3: codici referral e campo Compose

applyCode(code) è una chiamata suspend che convalida un codice e, se è valido, lo applica. I codici vengono ripuliti dagli spazi e messi in maiuscolo; uno non valido restituisce valid = false con un errorCode: INVALID_FORMAT, CODE_NOT_FOUND, CODE_EXPIRED, NETWORK_ERROR o UNKNOWN.

Con android-sdk-ui, InfluToReferralCodeInput è un composable Material 3 che convalida mentre l'utente scrive, applica il codice al tocco, lo precompila da un'installazione attribuita tramite link e accetta i tuoi testi tradotti. Mostra il nome del creator solo se attivi showReferrerName.

Passo 4: collega gli acquisti

InfluTo paga commissioni solo sugli acquisti verificati con lo store. Scegli un solo percorso per Android:

• RevenueCat: niente da collegare nel codice. Quando viene trovato un referral o applicato un codice, l'SDK trova l'SDK di RevenueCat e imposta influto_code e influto_referral; passa revenueCatAttributeSetter se vuoi essere esplicito. Configura prima RevenueCat e non aggiungere android-sdk-billing.

• Direttamente con lo store (Play Billing): aggiungi android-sdk-billing. In un'app che usa direttamente lo store, initialize avvia un observer con una propria connessione Play Billing, che segnala i nuovi acquisti e controlla quelli esistenti a ogni avvio. Vengono inviati solo gli acquisti PURCHASED, una sola volta ciascuno, in base al purchase token.

I prodotti una tantum e i consumabili richiedono productId più price e currency: senza productId l'acquisto viene verificato come abbonamento e fallisce, senza prezzo viene registrato a 0 $. Elencali in oneTimeProductIds e l'acquisizione automatica aggiunge entrambi. Un 409 significa che un acquisto una tantum è ancora in sospeso.

La maggior parte delle app ha un proprio BillingClient. Passa ogni acquisto al modulo anche dal tuo PurchasesUpdatedListener, così viene segnalato nel momento in cui avviene. Il modulo usa la stessa deduplicazione, quindi nulla viene segnalato due volte:

override fun onPurchasesUpdated(result: BillingResult, purchases: MutableList<Purchase>?) {
    if (result.responseCode != BillingClient.BillingResponseCode.OK || purchases == null) return
    scope.launch {
        for (purchase in purchases) {
            InfluToBilling.report(context, purchase) // subscriptions
            // one-time products: InfluToBilling.report(context, purchase, oneTime = true, price = 4.99, currency = "EUR")
        }
    }
}

Passo 5: aggiungi il service account di Google Play

Il metodo store-direct richiede l'accesso in lettura alla Google Play Developer API. InfluTo legge soltanto: non modifica mai nulla nella tua Play Console.

1. 1

   Abilita l'API. In Google Cloud abilita la Google Play Android Developer API e crea un account di servizio con una chiave JSON.

2. 2

   Concedi l'accesso nella Play Console. In Utenti e autorizzazioni, invita l'email dell'account di servizio e assegnagli View financial data, orders, and cancellation survey responses per l'app.

3. 3

   Carica, convalida, passa. Carica la chiave JSON in Impostazioni → Convalida e premi Salva e convalida. Quando il controllo è verde, imposta Android su Google — diretto.

Le nuove autorizzazioni di Google possono impiegare fino a 48 ore per raggiungere l'API; nel frattempo InfluTo mostra «in propagazione». Finché non passi al nuovo metodo, i report di acquisto ricevono un errore 400, quindi puoi rilasciare l'SDK prima senza rischi.

Passo 6: prova con un license tester

Gli acquisti di prova non spostano denaro e non cambiano le tue statistiche:

1. 1

   Simula un acquisto. Simula un acquisto in Setup e SDK invia un acquisto di prova sandbox attraverso la vera pipeline di InfluTo. Inserisci uno dei tuoi codici per vederlo associato.

2. 2

   Installa tramite un link di referral. Unisciti alla tua campagna con un secondo account creator, apri il suo link su un dispositivo di prova, installa la build di test e avviala. Digitare il codice è il test più affidabile.

3. 3

   Acquista come license tester. Acquista come license tester di Google Play. Il log di integrazione, impostato su Sandbox, mostra l'acquisto attribuito al tuo codice; con debug = true l'SDK registra ogni passaggio in Logcat con il tag InfluTo.

clearAttribution() azzera il dispositivo per un nuovo test; cancellare i dati dell'app o reinstallarla garantisce una partenza più pulita.

Note su Android

Qualche dettaglio sulla piattaforma:

• Prima le coroutine. I metodi di rete sono funzioni suspend; getReferralCode(), getPrefilledCode() e clearAttribution() sono funzioni normali.

• Autorizzazioni. Il core aggiunge INTERNET; android-sdk-billing aggiunge com.android.vending.BILLING. La documentazione sulla privacy spiega cosa dichiarare nel modulo Sicurezza dei dati di Play.

• Versione di Play Billing. android-sdk-billing espone Play Billing Library 9.0.0, che Gradle risolve insieme alla tua dipendenza Billing.

• Nessun ID pubblicitario. InfluTo non usa l'ID pubblicitario, non traccia gli utenti tra le app e non fa mai corrispondenze in base alle caratteristiche del dispositivo.

Oppure lascia fare al tuo agente di coding

Collega il server MCP di InfluTo a Claude Code, Codex o Cursor e chiedi l'integrazione: l'agente scrive le righe Gradle e il codice di avvio, ti dà un link per caricare tu stesso il JSON dell'account di servizio, esegue il controllo delle credenziali e conferma un acquisto di prova attribuito.