OneLink API

Premium
Para:
Última atualização:

Visão geral: a API do OneLink te ajuda a engajar usuários finais e aproveitar suas mídias próprias, criando links personalizados em campanhas em grande escala, via SMS e mais. Tanto o anunciante quanto o desenvolvedor são necessários para a implementação.

OneLink API

A OneLink API é usada para:

  • Criar, acessar, atualizar e deletar automaticamente URLs curtas do OneLink com parâmetros personalizados.
    Os parâmetros podem ser:
    • Parâmetros relacionados à atribuição, usados para mensurar e monitorar esforços de marketing, como canal de mídia, campanha e asset. Atenção: O parâmetro de canal de mídia (pid) é obrigatório.  
    • Parâmetros de personalização, que permitem configurar uma experiência de usuário personalizada ao abrir o aplicativo a partir de um link relevante. Esses parâmetros permitem que você envie usuários para um conteúdo personalizado no aplicativo. Por exemplo, uma página de produto específica, código de cupom ou promoção.
  • Permitir o compartilhamento de conteúdo do site e do aplicativo diretamente com usuários mobile (aumentando assim o engajamento e as instalações).
  • Gerar instantaneamente um grande número de links de atribuição personalizados do OneLink.
    Atenção: para links de referral, consulte o artigo de atribuição de convites de usuários. 

Exemplo

Feed Me, um serviço de entrega de supermercado, quer enviar um link personalizado via SMS para clientes existentes, incentivando-os a baixar o aplicativo Feed Me e comprar bananas. Com base no país do cliente, o Feed Me usa a API REST do OneLink para criar uma URL personalizada do OneLink que contém detalhes específicos para o país, a identidade do usuário e uma oferta especial para bananas na promoção.

A quantidade de consultas da OneLink API que você pode fazer é limitada dependendo do tipo de conta. Você pode ver quantas consultas você fez e quantas ainda restaram no dashboard da OneLink API. 

Você pode entrar em contato com seu CSM para aumentar o limite de consultas da API.  

Configuração

Para configurar a OneLink API:

  1. Crie um template do OneLink.
  2. Copie o ID do template do OneLink. 

  3. Copie o token da OneLink API. Um usuário administrador precisa recuperar a chave da API; os usuários da conta não têm esse acesso. 
  4. Forneça o OneLink ID e a chave da OneLink API ao desenvolvedor.
  5. Diga ao desenvolvedor para seguir as instruções no dev hub.

Dashboard

O dashboard da OneLink API exibeseu uso diário, mensal e trimestral da API.

Para visualizar o dashboard da OneLink API: 

Na AppsFlyer, no menu lateral, selecione Engajar > OneLink API.

Características e limitações

Característica

Considerações

Limite de cota da API
  • O limite de uso da OneLink API para criar, editar ou excluir links do OneLink é de 7,5 milhões por mês (fuso horário UTC), por conta.
  • Todas as solicitações feitas após ultrapassar essa cota não são atendidas, e os links não são criados; a chamada de API recebe o código de erro 429 com a mensagem "Cota mensal excedida".
  • As informações sobre quanto da cota foi usada/permanece são exibidas no dashboard da OneLink API. 

Limite de taxa
  • O limite de taxa da API por conta é de 500 solicitações por segundo (30.000 por minuto).
  • Todas as solicitações feitas acima de 500 solicitações por segundo (30.000 por minuto) não são atendidas, e os links não são criados; a chamada de API recebe o código de erro 429 com a mensagem "Limite de taxa excedido".

Visibilidade do link
  • Os links criados por meio da API não aparecem na lista de links personalizados do OneLink no dashboard da AppsFlyer.
  • Prática recomendada: salve os links criados por API em uma tabela local, para que você possa acessá-los para qualquer finalidade futura. 

TTL 
  • O tempo útil padrão (TTL) para URLs curtas do OneLink criadas via OneLink API é de 31 dias. Esse período se estende por mais 31 dias cada vez que o link recebe um clique. Quando o link recebe um clique depois que o TTL expira gera o mesmo comportamento definido na configuração de base do OneLink, mas a atribuição não funciona.
    • Podem ser necessárias até 48 horas para que uma URL curta do OneLink seja excluída após a expiração do TTL.
  • O TTL máximo é de 31 dias. Qualquer valor TTL maior que 31 é substituído com o TTL padrão de 31.
  • Você pode alterar o TTL padrão adicionando o parâmetro ttl={value} e especificando dias, horas ou minutos. Por exemplo ttl=7d, ttl=12h, ou ttl=10m.
  • Você pode enviar uma solicitação de atualização para especificar o TTL. Qualquer solicitação de atualização redefine o TTL (para links existentes) para aquele especificado no corpo da solicitação.
    • Isso significa que o TTL é substituído. Por exemplo, se você fizer uma chamada de atualização com TTL de 2d (2 dias) para um link que atualmente tem TTL de 29d, ele mudará para TTL=2d (não 31d).
    • Uma chamada de atualização pode potencialmente prolongar a vida útil do link de atribuição. Por exemplo, se você fizer uma chamada de atualização com TTL de 31d para um link que atualmente tem TTL de 20d, mas 5 dias se passaram, o TTL será de 31d a partir do momento da atualização.
  • Se você não quiser que os TTLs dos links sejam estendidos automaticamente, adicione o parâmetro renew_ttl=false em seus links. O valor deste parâmetro é boolean, true (padrão) ou false.
  • O parâmetro renew_ttl não é exibido na URL real.

Caracteres especiais

Os seguintes caracteres devem ser codificados se usados para links criados pela API: ;, *, !, @, #, ?, $, ^, :, &, ~, `, =, +, ', >, <, /
Se você não codificar esses caracteres, eles serão substituídos por um espaço em branco, e o link e sua funcionalidade poderão quebrar.


Atenção: Os 3 parâmetros a seguir não serão decodificados quando o link for clicado e permanecerão codificados:

  • af_dp
  • deep_link_value
  • deep_link_sub1

Payload

A string de consulta do payload não pode exceder 2.048 caracteres.

URL ID

O URL ID (ou shortlink ID) pode ser editado para destacar a oferta da sua campanha. Por exemplo: https://meuapp.onelink.com/abc123/maçãs. O URL ID não deve ultrapassar 50 caracteres e pode conter uma combinação de letras e números. Por padrão, são 8 caracteres.

Atenção:

  • Você só pode editar o URL ID se o ID atual ainda não estiver em uso.
  • Se o URL ID já estiver em uso, a criação do link falhará e retornará uma resposta de erro (400). Você e seu desenvolvedor precisam decidir e configurar o que acontecerá nesse caso.
  • A chamada com falha ainda conta para sua cota mensal de API.