SDK para iOS

Swift, que também pode ser chamado a partir de Objective-C. Sem dependências. Inclui um manifesto de privacidade. Plano Pro ou superior.

Requisitos

• iOS 13+.
• Swift ou Objective-C.
• Uma chave do SDK: no painel, abra seu app → Configurações → Chaves do SDK → Nova chave. Ela aparece uma única vez, então copie-a nesse momento.

Instalação

No Xcode, escolha File → Add Package Dependencies…, cole o endereço do repositório, escolha Up to Next Major Version a partir de 0.3.3 e adicione a biblioteca Unolink ao target do seu app.

https://github.com/unolink-dev/unolink-sdk

O Unolink é instalado pelo Swift Package Manager, não pelo CocoaPods. Se o seu projeto também usa CocoaPods para outras bibliotecas e o pod install falha com um erro de codificação (Ruby 4, ou um locale que não é UTF-8), rode em UTF-8:

LANG=en_US.UTF-8 pod install

Configuração

Chame configure uma vez, o mais cedo possível: no init() do seu App @main, ou em application(_:didFinishLaunchingWithOptions:).

import Unolink

@main
struct MyApp: App {
    init() {
        #if DEBUG
        Unolink.configure(apiKey: "ulk_…", options: UnolinkOptions(debug: true))
        #else
        Unolink.configure(apiKey: "ulk_…")
        #endif
    }
    var body: some Scene { WindowGroup { ContentView() } }
}

Uma biblioteca compilada não enxerga as configurações da sua build, então passe você mesmo debug: true nas builds de depuração, como acima. Isso marca a instalação como dispositivo de teste.

Objective-C:

@import Unolink;

[Unolink configureWithApiKey:@"ulk_…" options:[UNLOptions new]];

Opções

Unolink.configure(apiKey: "ulk_…", options: UnolinkOptions(logLevel: .debug, debug: true))

A chave é pública: ela vai dentro do seu app e só pode reportar dados desse app. Veja Chaves do SDK.

Eventos do funil

Adicione uma linha em cada momento importante. Elas viram as etapas em Funil e Jornadas.

Unolink.onboardingCompleted()                       // the last onboarding screen is done
Unolink.paywallViewed(placement: "onboarding")      // a paywall appeared; placement says which one
Unolink.paywallSkipped(placement: "onboarding")     // closed without buying
Unolink.signUp(method: "apple")                     // an account was created
Unolink.signUpSkipped()                             // went on as a guest (0.3.2+)

Sem RevenueCat, reporte você mesmo os testes grátis e as compras. O valor é um Decimal, então os preços nunca são arredondados:

Unolink.trialStarted(productId: "pro_yearly")
Unolink.purchase(amount: product.price, currency: "USD", productId: product.id)
Unolink.purchaseCancelled(productId: product.id)    // closed the purchase sheet
Unolink.purchaseFailed(productId: product.id, reason: "payment_failed")

Seus próprios eventos recebem um nome e até 20 propriedades:

Unolink.track("level_up", properties: ["level": 3])

Objective-C:

[Unolink paywallViewedWithPlacement:@"onboarding" properties:nil];
[Unolink purchaseWithAmount:[NSDecimalNumber decimalNumberWithString:@"49.99"] currency:@"USD" productId:nil properties:nil];

A lista completa, com os nomes que chegam ao painel, está em Eventos.

ID de usuário e RevenueCat

Se você usa RevenueCat, conecte-o no seu app → Configurações → RevenueCat. Depois disso, não chame purchase nem trialStarted: o próprio RevenueCat envia testes grátis, compras, renovações, cancelamentos e reembolsos, e o Unolink ignora as chamadas de compra do app para que nada conte duas vezes.

Para ligar essas compras à instalação, informe o próprio app user ID do RevenueCat. Com o SDK 0.3.2 ou posterior, uma linha o mantém atualizado. Chame-a uma vez na abertura, antes ou depois de configure:

Unolink.connectRevenueCat { Purchases.isConfigured ? Purchases.shared.appUserID : nil }

O Unolink lê o ID na abertura, sempre que o app fica ativo e antes de cada evento, e só o envia quando ele mudou. Depois de Purchases.logIn e Purchases.logOut, chame Unolink.revenueCatUserChanged() para enviar o novo ID na hora. Retorne nil enquanto o RevenueCat não estiver configurado: ler Purchases.shared antes disso derruba o app.

Sem ela (ou antes da 0.3.2), chame setUserId com o ID do RevenueCat depois de Purchases.configure, depois de cada Purchases.logIn e Purchases.logOut, e em toda abertura. Use um ou outro, não os dois:

// after Purchases.configure, logIn and logOut, and on every launch
Unolink.setUserId(Purchases.shared.appUserID)

Para um convidado, esse é o ID anônimo do RevenueCat, então uma compra feita antes do cadastro se junta à instalação na hora. Depois do logIn, é o ID da conta. Todo ID que uma instalação reportou conta, então a compra do convidado continua ligada. Veja Convidados e contas.

O Unolink nunca guarda o ID em si, apenas um hash unidirecional que é diferente para cada um dos seus apps.

Deep links no iPhone

Deep links adiados são só para Android. A Apple não dá aos apps um referrer de instalação, então o seu app não tem como saber em qual link a pessoa tocou, e o Unolink nunca faz fingerprinting de dispositivos para adivinhar. Unolink.onDeferredDeepLink(_:) existe para que o código possa ser compartilhado entre plataformas, mas no iPhone ele não é chamado hoje.

No painel, as instalações no iPhone são associadas ao clique no link de onde vieram, sem fingerprinting. A associação não é enviada ao app. Desative-a por app nas Configurações dele.

Seus links continuam mandando os visitantes de iPhone direto para a App Store e contando os cliques deles, e o SDK continua contando cada instalação e cada evento.

Outras chamadas

Como ele se comporta

• Primeira abertura: cria um ID de instalação aleatório em Application Support (fora do backup do iCloud, nunca no Keychain), então uma reinstalação ou um celular novo é uma nova instalação.
• Eventos automáticos: first_open, session_start (na abertura, ou após 30 minutos em segundo plano) e app_background. Eles são grátis.
• Os eventos são guardados no dispositivo (até 1.000) e enviados em lotes a cada 15 segundos enquanto o app está ativo, e quando ele vai para segundo plano. Sem conexão, eles esperam e tentam de novo.
• Ele nunca bloqueia a thread principal e nunca lança exceções.

Dispositivos de teste

Configure com debug: true nas builds de depuração, como acima. Os dados delas são reais, mas ficam ocultos até você ativar Incluir dispositivos de teste em Funil e Jornadas. Mais em Testes.

Privacidade

• Sem IDFA, sem o aviso do App Tracking Transparency, sem fingerprinting.
• O manifesto de privacidade incluído declara interação com o produto (seus eventos) e histórico de compras (as compras que você reporta), usados para análises, não vinculados à identidade, e nenhum rastreamento. Use as mesmas respostas no rótulo de privacidade da App Store.
• Um ID de instalação aleatório, versão do app, versão do sistema, versão do SDK, celular ou tablet, idioma. O país vem da borda da rede. Endereços IP nunca são guardados.
• Nunca coloque nomes, e-mails ou outros dados pessoais nas propriedades dos eventos.

Solução de problemas

• Nada no painel? Ative Incluir dispositivos de teste: builds de depuração com debug: true ficam ocultas por padrão.
• Ainda nada? Configure com UnolinkOptions(logLevel: .debug, debug: true) e procure por [Unolink] no console do Xcode. Uma chave errada ou revogada aparece no log como erro.
• Algumas instalações no iPhone sem link? É esperado: nem toda instalação no iPhone pode ser associada a um clique, e essas aparecem em uma linha própria. Veja Deep links no iPhone.

Mais em Solução de problemas.