Firebase Dynamic Links: o que é, criação de links e integração

O que são Firebase Dynamic Links

Firebase Dynamic Links é uma tecnologia do Google que cria um único link que leva ao conteúdo desejado em um aplicativo móvel ou site, adaptando o comportamento conforme a plataforma e o estado de instalação. O link verifica se o aplicativo está instalado no dispositivo: se sim — abre-o com os parâmetros passados, se não — redireciona para Google Play ou App Store para instalação, e após a instalação redireciona para a tela de destino.

Característica principal: Deferred Deep Linking

A principal vantagem do Dynamic Links sobre os links profundos comuns é o suporte a links profundos adiados. Deferred Deep Linking significa que o contexto de transição (parâmetros do link) é preservado mesmo se o aplicativo ainda não estiver instalado. Quando o usuário instala o aplicativo da loja, o Dynamic Links SDK lê o contexto salvo e o passa para a tela desejada. Sem esta tecnologia, o usuário simplesmente cairia na tela principal após a instalação, perdendo o código promocional, convite ou link para um pedido específico.

Casos de uso

Dynamic Links são usados em programas de indicação para atrair novos usuários com atribuição à conta do convidador. Campanhas de marketing com transições de newsletters por email e redes sociais usam Dynamic Links para medição precisa de conversão. Em cenários de integração, o link leva um novo usuário a uma tela de boas-vindas com conteúdo personalizado. No e-commerce, links de produtos preservam o contexto e levam ao cartão do produto mesmo no primeiro lançamento após a instalação.

Como funcionam os links dinâmicos

O mecanismo de funcionamento do Dynamic Links consiste em várias etapas, cada uma podendo variar conforme o estado do aplicativo. Quando um usuário clica em um link dinâmico, o navegador envia uma solicitação ao servidor Firebase. O Firebase verifica se o aplicativo está instalado através da verificação de intent-filter ou universal link. Se o aplicativo estiver instalado, o Firebase abre-o com o link profundo passado. Se não — redireciona para a página da loja ou versão web.

Anatomia de um link dinâmico

Um Dynamic Link padrão consiste em uma URL base, parâmetros de link e tags de marketing opcionais. A URL base é um domínio como your-app.page.link registrado no Firebase Console. Parâmetros de link profundo são definidos através de parâmetros de consulta: link (URL de destino dentro do aplicativo), apn (Android Package Name), ibi (iOS Bundle ID), st e sd (título e descrição para pré-visualização social). Tags de marketing utm_source, utm_medium, utm_campaign são passadas para o Google Analytics para rastreamento.

Criação de links através do Firebase Console e API

Firebase Console fornece uma interface visual para criar Dynamic Links na seção Engage > Dynamic Links. No console, você pode definir todos os parâmetros do link, incluindo o link profundo, comportamento web, metadados sociais e tags UTM. Após criar o link, o console fornece uma URL pronta para uso, bem como estatísticas de cliques e transições. Para criação em massa de links, é usada a REST API do Firebase Dynamic Links com autenticação OAuth 2.0.

Criação de um link através da REST API

Para criação programática de Dynamic Links, é feita uma solicitação POST à API do Firebase Dynamic Links. O corpo da solicitação contém dynamicLinkInfo com parâmetros de link profundo, configurações de plataforma e metadados sociais. A API retorna uma URL pronta para uso como https://your-app.page.link/abc123. Para links de longa duração, é usado suffix.option = UNIQUE — links curtos com um sufixo único. Para links temporários — SHORT, com possíveis colisões.

const axios = require("axios")

const apiUrl = "https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=API_KEY"

const data = {
    dynamicLinkInfo: {
        domainUriPrefix: "https://yourapp.page.link",
        link: "https://yourapp.com/promo/summer",
        androidInfo: { androidPackageName: "com.example.myapp" },
        iosInfo: { iosBundleId: "com.example.myapp.ios" },
        socialMetaTagInfo: {
            socialTitle: "Promoção de verão",
            socialDescription: "Até 50% de desconto até o final do mês"
        }
    },
    suffix: { option: "UNIQUE" }
}

axios.post(apiUrl, data)
    .then(res => console.log(res.data.shortLink))
    .catch(err => console.error(err))

Links curtos e tags UTM

Dynamic Links geram automaticamente URLs curtas com 6–8 caracteres após o domínio, tornando-as adequadas para uso em SMS e redes sociais. Parâmetros UTM são adicionados através do campo utmParameters ou diretamente no parâmetro link. O Firebase vincula automaticamente cliques em Dynamic Links com o Google Analytics para Firebase, permitindo rastrear tráfego de referência e atribuição de campanhas.

Integração de Dynamic Links no Android

Configurar Dynamic Links no Android inclui adicionar o Firebase SDK, configurar o intent-filter para a activity que recebe links profundos e processar links através do Firebase Dynamic Links SDK. Após instalar o SDK e adicionar google-services.json, você precisa registrar a activity no AndroidManifest.xml com um intent-filter para processar links do domínio do seu aplicativo.

Configurar intent-filter no AndroidManifest

A activity que processa Dynamic Links deve ter um intent-filter para a ação VIEW e as categorias DEFAULT e BROWSABLE. AndroidManifest.xml inclui uma tag data com android:scheme, android:host e android:pathPrefix correspondentes ao seu link profundo. Para processar links do domínio page.link, também é adicionado um intent-filter com o esquema https e o host do seu domínio Dynamic Links.

<!-- AndroidManifest.xml -->
<activity android:name=".MainActivity">
    <intent-filter>
        <action android:name=
            "android.intent.action.VIEW" />
        <category android:name=
            "android.intent.category.DEFAULT" />
        <category android:name=
            "android.intent.category.BROWSABLE" />
        <data android:scheme="https"
            android:host="yourapp.com"
            android:pathPrefix="/promo" />
    </intent-filter>
</activity>

Processamento do link no código

Após configurar o intent-filter, você precisa processar o Dynamic Link recebido no código da Activity. A API FirebaseDynamicLinks recebe o link do intent e retorna um objeto PendingDynamicLinkData com os parâmetros extraídos. O método getLink retorna o link profundo de destino, que pode ser analisado e usado para navegação. É importante processar o link tanto na inicialização a frio (via getIntent em onCreate) quanto na inicialização a quente (via onNewIntent).

Integração de Dynamic Links no iOS

Configurar Dynamic Links no iOS requer configuração tanto no lado do Firebase quanto no projeto Xcode. Você precisa carregar uma chave APNs no Firebase Console, adicionar o Firebase SDK via Swift Package Manager ou CocoaPods e configurar o App Delegate para processar Universal Links. Dynamic Links no iOS usam Universal Links para transição perfeita entre o navegador e o aplicativo sem uma página intermediária.

Configurar Universal Links

Universal Links é uma tecnologia da Apple que conecta seu domínio a um aplicativo móvel. O arquivo apple-app-site-association (AASA) é carregado no servidor em https://your-app.page.link/apple-app-site-association. O Firebase cria e mantém automaticamente este arquivo para seu domínio Dynamic Links. No Xcode, você precisa habilitar Associated Domains e especificar applinks:your-app.page.link nas Capacidades do projeto.

Processamento do link através do Firebase SDK

Para iOS, o processamento de Dynamic Links é feito através do Firebase SDK no App Delegate ou Scene Delegate. O método application:continueUserActivity: intercepta o Universal Link recebido e o passa para a API do Firebase Dynamic Links, que extrai o link de destino e os parâmetros. O Firebase SDK lida automaticamente com Deferred Deep Links solicitando dados de instalação através do armazenamento de curto prazo da Firebase Installation API.

import FirebaseDynamicLinks

class AppDelegate: UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping
            ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        return DynamicLinks.dynamicLinks()
            .handleUniversalLink(userActivity.webpageURL!) {
                dynamicLink, error in
                if let link = dynamicLink?.url {
                    self.handleDeepLink(link)
                }
            }
    }
}

Exemplo de implementação em Kotlin

Vamos ver um exemplo completo de processamento de um Dynamic Link em um aplicativo Android usando Kotlin. MainActivity lê o Dynamic Link recebido tanto na inicialização a frio quanto a quente do aplicativo. O link é analisado em parâmetros que são usados para navegação até a tela desejada com os argumentos passados. O exemplo mostra o processamento de um link para uma página de promoção com um identificador de campanha promocional.

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        handleDynamicLink(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handleDynamicLink(intent)
    }

    private fun handleDynamicLink(intent: Intent) {
        FirebaseDynamicLinks.getInstance()
            .getDynamicLink(intent)
            .addOnSuccessListener { data ->
                val deepLink = data?.link ?: return@addOnSuccessListener
                val promoId = deepLink
                    .getQueryParameter("promoId") ?: ""
                if (promoId.isNotEmpty()) {
                    navigateToPromoScreen(promoId)
                }
            }
            .addOnFailureListener { e ->
                Log.e("DL", "Erro ao processar o link", e)
            }
    }
}

Testar Dynamic Links

Para testar Dynamic Links, o Firebase Console é usado, onde você pode criar um link de teste e enviá-lo para um dispositivo via messenger ou email. O depurador do Firebase Dynamic Links está disponível em https://your-app.page.link/?d=1 e exibe informações detalhadas sobre o comportamento do link. Ao testar Deferred Deep Links, você precisa garantir que o aplicativo esteja desinstalado e, após a instalação, o link leve à tela correta com os parâmetros passados.