Gerar URI deep link de app móvel

ref=email. Equipes de produto, crescimento e engenharia precisam que essas URIs de deep link estejam bem formadas sempre: um token de scheme legal, host e path previsíveis, e pares de query percent-encoded que sobrevivam a copiar e colar em payloads push, SMS, códigos QR e destinos de anúncio. Esta capacidade aceita um scheme personalizado, host opcional, path opcional e uma lista opcional de pares chave/valor de query, valida o scheme contra a produção RFC 3986, normaliza o path, codifica a query e devolve a string deep_link pronta mais campos de eco estruturados. Caracteres inválidos no scheme falham com invalid_input em vez de emitir uma URI quebrada em silêncio.

O que é um deep link com scheme personalizado e como a URI é montada

Um deep link móvel com scheme personalizado é uma URI que o sistema operacional encaminha para o seu aplicativo instalado em vez do navegador. O scheme é o token antes dos dois pontos e da barra dupla—myapp, com.example.app ou my-app+v2—e deve seguir a gramática de schemes URI: uma letra primeiro, depois apenas letras, dígitos, mais, ponto ou hífen. Espaços, underscores, dois-pontos e barras dentro do scheme são ilegais e são os erros mais comuns de copiar e colar quando um nome de produto é usado como scheme sem sanitizar. Chaves e valores de query são percent-encoded com as mesmas regras que os navegadores usam para componentes no estilo application/x-www-form-urlencoded, de modo que espaços viram escapes estilo %20 e caracteres reservados não podem partir a query. Após scheme:// vem um host opcional (às vezes chamado authority), como product, open ou auth, depois um path opcional como /item/42, e em seguida uma string de query opcional de pares chave igual valor unidos por ampersands. Este montador concatena essas peças em ordem fixa: scheme, literal ://, host (pode estar vazio), um path que sempre ganha uma única barra inicial quando não vazio, e uma string de query só quando há pelo menos um parâmetro. Quando o host está vazio e o path é /promo, o resultado parece myapp:///promo; quando host e path estão vazios, você ainda obtém um casco legal scheme:// útil como intent bare de abrir o app. A resposta ecoa scheme, host, path, query_params, query_string, deep_link e has_query para que clientes registrem partes estruturadas sem reanalisar a URI. Como o algoritmo é puro e determinístico, as mesmas entradas sempre produzem o mesmo deep_link byte a byte no caminho gratuito do navegador e no caminho pago da API.

Contrato de entrada, regras de validação e comportamento de erro

No máximo cinquenta pares são aceitos. Envie por POST um corpo JSON com scheme como o único campo estritamente obrigatório: uma string não vazia após o trim que combine com o padrão letra e depois letras, dígitos, mais, ponto ou hífen. Os aliases url_scheme, custom_scheme e protocol são aceitos. host é opcional e o padrão é a string vazia; quando definido não deve conter espaços, barra, interrogação nem hash. path é opcional; quando não vazio não deve conter espaços, interrogação nem hash, e uma barra inicial é inserida se você omitir, de modo que item/42 vira /item/42. query_params é um array opcional de objetos, cada um com key obrigatória e value opcional (padrão string vazia); os aliases query, params e search_params funcionam igual. Cada key deve ser não vazia após o trim; valores podem ser strings, números ou booleanos e são convertidos para string antes da codificação. scheme ausente ou vazio, scheme com caracteres inválidos, caracteres ilegais em host ou path, query_params que não seja array ou keys em branco falham com invalid_input e uma mensagem clara que nomeia o problema—essas falhas não são cobradas. Em caso de sucesso você recebe scheme, host e path normalizados; a lista query_params normalizada; query_string sem interrogação inicial; deep_link como URI completa; e has_query como booleano. Exemplo: scheme myapp, host product, path /item/42 e query_params ref igual a email mais utm_source igual a newsletter produz myapp://product/item/42? ref=email&utm_source=newsletter. Combine deep_link com os domínios associados ou intent filters do seu app no cliente; este endpoint só monta a string URI e não registra schemes no SO nem verifica se o app está instalado.

Onde um montador de URI deep link se paga

Backends de notificação push compõem scheme, host de tela e id de entidade em um único campo deep_link que o cliente móvel pode analisar em cold start. Apps white-label multi-tenant mapeiam cada marca ao seu próprio token de scheme e ainda compartilham um montador para convenções de path e query. Como a implementação é parse puro tier A, cada chamada bem-sucedida custa o preço base publicado US$ 0,002 sem tokens de modelo e sem rede de saída.