Conceitos básicos
Contas monitoradas e palavras-chave são coisas diferentes
Uma conta monitorada é uma conta que você observa; você recebe tudo o que ela faz, ou só os tipos de evento que escolher. Uma palavra-chave é uma busca que você observa em todo o X; você recebe publicações de qualquer pessoa que correspondam a ela, como eventos search.match. Contas monitoradas são identificadas pelo nome de usuário, palavras-chave pelo texto da busca, e uma chave comporta qualquer quantidade de cada uma até os limites do seu plano.
Uma conta é o seu id, não o seu nome de usuário
Você monitora uma conta, identificada pelo id numérico no X (id em um Target). Uma conta pode mudar o nome de usuário (screen_name) ou o nome de exibição a qualquer momento: você continua recebendo os eventos dela, os seguintes trazem o novo nome em target.screen_name e um evento profile.screen_name ou profile.name informa o que mudou. Indexe seus dados pelo id. Onde a API pede uma conta, você pode indicá-la pelo user_id, pelo nome atual ou por um que ela teve antes.
Entrega em duas fases: create, depois update
Alguns eventos de publicação são entregues em dois frames. O primeiro, op: "create", traz o essencial — o id da publicação, o autor e o texto — para que você possa agir imediatamente. Um instante depois, o mesmo id de evento chega de novo com op: "update", agora com mídia, o original citado ou respondido, contagens e o restante. Eventos que já estão completos na primeira vez não têm segundo frame; GET /v1/meta/event-types informa quais tipos podem ter um.
create. Se precisa da publicação inteira, espere o update do mesmo id. Em qualquer caso, indexe seu armazenamento pelo id e deixe um update posterior sobrescrever o que você guardou. O tipo só muda entre os dois frames de um jeito: um primeiro tweet.create com kind_final: false pode virar tweet.quote. Se você trata publicações originais e citações de forma diferente, classifique esse frame quando o update dele chegar.Pelo menos uma vez, nunca exatamente uma vez
Cada conta monitorada é observada por vários caminhos independentes ao mesmo tempo, de modo que um caminho com falha não custa nada a você. O primeiro a reportar uma determinada alteração vence e se torna o evento; os outros são registrados como corroboração em vez de entregues de novo. Em uma reconexão, porém, você pode ver um evento que já tem. Deduplique pelo id.
Posição e replay
Cada evento carrega um sid — sua posição no nosso log. Persista o último que você processou; ao reconectar, passe-o como ?last_id= e enviamos tudo o que veio depois dele antes de retomar ao vivo. O log guarda 24 horas, e uma única reconexão repete no máximo 5.000 eventos. Contas monitoradas ou palavras-chave que você adiciona com um socket aberto começam a fluir por ele em até 30 segundos; você não precisa reconectar.