Migrando de outro provedor

Trocar de provedor de push costuma significar reescrever a camada de integração inteira. Aqui não: o /api/v1 do PushMesh fala o formato clássico de push do mercado — o modelo player, com include_player_ids, contents, included_segments e companhia.

Na prática, o lado do servidor é apontar a URL base e trocar a chave. O lado do aplicativo dá mais trabalho, e esta página é honesta sobre isso: há passos manuais e há uma etapa que depende da sua curva de atualização de app. Ninguém migra uma base de aparelhos por chave de API.

---

O retrato honesto em três linhas

---

Parte 1 — O servidor

O que já está no formato que você conhece

Envio, POST /api/v1/notifications, com os nomes clássicos:

Semânticas preservadas, inclusive as esquisitas:

• url / app_url / web_url viram o destino do toque, nessa precedência;

• os flags de plataforma seguem a lógica por exclusão: ausente inclui, false explícito exclui. isIos: true não restringe nada;

• ninguém alcançável não é erro — é 200 com id vazio:

  { "errors": ["All included players are not subscribed"], "id": "", "recipients": 0 }

• envio parcial também é 200, com errors como objeto:

  { "errors": { "invalid_player_ids": ["1111…"] }, "id": "0198…", "recipients": 1 }

Segmentos reconhecidos: Subscribed Users, Total Subscriptions (apelido do primeiro), Active Users (visto nos últimos 7 dias) e Engaged Users (com recibo nos últimos 7 dias).

A troca

# antes
curl -X POST https://<provedor-anterior>/api/v1/notifications \
  -H "Authorization: Basic $CHAVE_ANTIGA" ...

# depois
curl -X POST https://api.pushmesh.io/api/v1/notifications \
  -H "Authorization: Basic $PUSHMESH_KEY" ...

A chave tem o formato pm_live_<identificador>_<segredo> e vai em Authorization: Basic. Também são aceitos Bearer <chave> e o Basic com base64 de usuario:chave — o que o seu cliente HTTP já fizer, funciona.

Diferenças que valem um teste antes do corte

Um desserializador tipado com errors fixo como lista de strings quebra exatamente no cenário mais comum de migração — uma lista com identificadores antigos, que responde com errors objeto. Ajuste isso antes de virar.

O que é recusado de propósito

Estes campos respondem 400 nomeado em vez de serem aceitos em silêncio. Aceitar e ignorar mandaria a mensagem errada para a base toda sem avisar ninguém:

web_buttons é a única exceção: aceito e ignorado, porque integrações antigas mandam array vazio.

Leia essa tabela antes de decidir. Se a sua operação depende de filters ou de modelos de mensagem, a migração exige refazer isso no seu lado — e é melhor descobrir agora do que na véspera.

---

Parte 2 — O aplicativo

React Native

npm install @pushmesh/sdk

O SDK tem uma superfície clássica justamente para você não reescrever as chamadas do app:

import { ClassicApi } from '@pushmesh/sdk/compat';

await ClassicApi.initialize(APP_ID, { baseUrl: 'https://api.pushmesh.io' });

await ClassicApi.login('usuario-42');
await ClassicApi.Notifications.requestPermission();
await ClassicApi.User.addTags({ plano: 'pro' });
ClassicApi.InAppMessages.addTrigger('tela', 'checkout');

Cobre initialize, login/logout, permissão, listeners de notificação, tags de usuário e gatilhos de in-app. Onde os nomes batem, a troca é o import.

A API nativa do SDK é a mesma coisa com nomes próprios:

import { PushMesh } from '@pushmesh/sdk';

await PushMesh.init({ appId: APP_ID, baseUrl: 'https://api.pushmesh.io' });
await PushMesh.login('usuario-42');

baseUrl não é opcional na versão publicada hoje. O pacote @pushmesh/sdk@0.7.2 traz outro endereço embutido como padrão para quando o campo é omitido, e esse endereço não está no ar: o aparelho não registra e nenhum erro de servidor aparece, porque a chamada nem sai. Passe baseUrl: 'https://api.pushmesh.io' nos dois caminhos — PushMesh.init e ClassicApi.initialize — até uma versão nova corrigir o padrão. É a primeira coisa a conferir se a base nova não cresce depois da publicação do app.

O que precisa da sua atenção no app

1. Remova o SDK anterior. Dois SDKs de push disputando o token do aparelho é a receita para o push sumir sem erro nenhum.
2. Cadastre os parâmetros do Firebase no painel (Android). O SDK os busca no boot — o app deixa de precisar do arquivo de configuração embutido. E não confunda com a credencial que envia: as duas estão em Credenciais de entrega.
3. Confirme o envio do token no seu fluxo de renovação.
4. Não coloque a chave da API no aplicativo. As rotas que o app usa não pedem credencial exatamente por isso: um APK publicado é um segredo publicado.

---

Parte 3 — A base de aparelhos (a parte que não é mágica)

Não existe botão de importar base. Existem dois caminhos, e você provavelmente vai usar os dois.

Caminho A — registro orgânico (o padrão, seguro)

Você publica a versão do app com o SDK novo. Cada aparelho que abre o app se registra, e o player_id nasce daquele registro. A base cresce na velocidade da sua adoção de versão.

• Vantagem: zero risco, zero trabalho, e a base que se forma é composta só de aparelhos vivos.
• Custo: leva o tempo da sua curva de atualização — semanas, tipicamente.
• Continuidade da identidade: mande external_user_id no login e o seu identificador de sempre continua valendo. É o que faz a segmentação do seu lado sobreviver à troca.

Caminho B — registro em massa dos tokens que você já tem

Se você guarda a lista de tokens de push, dá para registrá-los diretamente:

curl -X POST https://api.pushmesh.io/api/v1/players \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "'"$APP_ID"'",
    "device_type": 1,
    "identifier": "<token de push do aparelho>",
    "external_user_id": "usuario-42"
  }'

A rota é idempotente por token: registrar duas vezes devolve o mesmo player_id.

Antes de contar com isso, confira se os tokens continuam válidos:

• Android: o token está vinculado ao projeto Firebase. Se você mantiver o mesmo projeto, os tokens continuam valendo. Se trocar de projeto, não valem — e não há como convertê-los.
• iOS: o token está vinculado ao aplicativo e ao ambiente de notificação, e não ao provedor. Mantendo o mesmo aplicativo e enviando a mesma chave de autenticação, eles continuam valendo.

E confira o custo de tempo, que costuma surpreender: a rota de registro tem teto de 120 requisições por minuto por endereço de origem e o aplicativo tem teto de 50.000 registros de aparelho por hora. Uma base grande, saindo de um único servidor, leva dias. Se esse for o seu caso, fale com a gente antes de começar, em vez de descobrir batendo em 429.

Uma observação que evita expectativa errada: um token registrado por essa via só é alcançável de fato quando o aparelho está rodando um app capaz de receber pelo PushMesh. Registrar o token não instala o SDK.

---

Parte 4 — Rodando os dois em paralelo

O modo mais seguro de virar é não virar de uma vez.

1. Publique o app com o SDK novo, mantendo o provedor anterior ativo.

2. Espere a adoção subir. Nada muda no seu envio ainda.

3. Meça a base nova com o export, que devolve quem está vivo:

   curl -X POST "https://api.pushmesh.io/api/v1/players/csv_export?app_id=$APP_ID" \
     -H "Authorization: Basic $PUSHMESH_KEY"

   {
     "csv_file_url": "https://…/exports/…/players-20260827T150000Z-….csv.gz",
     "pm_pronto_em_s_estimado": 30,
     "pm_validade_h": 72
   }

   O arquivo é CSV comprimido, com as colunas id,external_user_id,notification_types,invalid_identifier,last_active. Baixe a URL: ela responde 404 enquanto o arquivo não fica pronto e 200 quando fica. A URL é a credencial — o arquivo é público para quem tiver o endereço, e ele carrega os seus identificadores de usuário. Não cole em ticket nem em chat.

4. Dispare em paralelo para uma fatia pequena, dos dois lados, e compare. Aqui você tem uma vantagem que a comparação costuma revelar: além de successful (o provedor aceitou), o PushMesh devolve recebidos — a confirmação vinda do próprio aparelho.

5. Vire o tráfego quando a base nova cobrir o que você precisa.

6. Desligue o provedor anterior.

---

Checklist

Servidor

• URL base apontada para https://api.pushmesh.io
• Chave nova no cofre; nenhuma chave no repositório
• Nenhum campo da tabela de recusados no seu payload
• errors tratado como união de array e objeto
• Ramificação por status HTTP, não por texto de erro
• Idempotency-Key nos envios que não podem duplicar

Aplicativo

• SDK anterior removido
• @pushmesh/sdk instalado e inicializado no boot com baseUrl
• Parâmetros do Firebase cadastrados no painel (Android)
• external_user_id enviado no login
• Nenhuma chave de API embutida no app

Base

• Caminho escolhido (orgânico, em massa, ou os dois)
• Se em massa: validade dos tokens confirmada e ritmo combinado
• Período de paralelo definido
• Export conferido antes do corte

---

Onde pedir ajuda

Se algo nesta página não bater com o que você está vendo na prática, é a página que está errada — e queremos saber. Toda resposta da API traz o cabeçalho X-Pm-Request-Id; cite esse identificador e a gente encontra a chamada exata.