Uma introdução prática à API Twitch Helix

Por trás de quase todas as ferramentas Twitch que você já viu, os rastreadores de estatísticas, os bots de moderação, as sobreposições de stream, os sistemas de alerta, existe uma interface: a API Twitch Helix. Twitch é extraordinariamente generoso com dados públicos, e Helix é a porta para isso. Se você já se perguntou como sites de terceiros sabem quem está ao vivo, como é a audiência de um canal ou detalhes que uma página de perfil do Twitch nem sequer exibe, este é o mecanismo.

Este artigo é uma visão prática do Helix para desenvolvedores que ainda não o usaram: o que ele oferece, como funciona sua autenticação, o que as pessoas constroem com ele e onde estão as arestas vivas.

O que é hélice

Hélice é API REST atual do Twitchveiculado em api.twitch.tv/helix. Ele substituiu a antiga API “Kraken”, que foi totalmente desativada em 2022, portanto, qualquer tutorial que ainda mostre os endpoints do Kraken é um sinal para continuar rolando. Helix cobre usuários, streams, canais, jogos e categorias, clipes, bate-papo, ações de moderação, assinaturas e eventos, com entrada e saída JSON.

Duas coisas o distinguem de muitas APIs de plataforma. Primeiro, uma grande parte dele funciona sem a permissão do usuário, porque os dados são públicos pela própria definição do Twitch. Em segundo lugar, ele é emparelhado com EventSub, um sistema push que notifica seu aplicativo quando algo acontece (um stream entra ao vivo, um usuário segue, uma mensagem chega) em vez de forçá-lo a fazer uma pesquisa. As ferramentas Twitch mais sérias usam ambos: Helix para pesquisas, EventSub para eventos ao vivo.

Autenticação, em termos simples

A autenticação é onde a maioria dos recém-chegados fica paralisada, principalmente porque o Twitch oferece vários fluxos OAuth e os tutoriais raramente dizem qual deles você realmente precisa. A versão curta:

Cada solicitação precisa de um ID de cliente, que você obtém registrando um aplicativo no console do desenvolvedor Twitch (é necessária primeiro a autenticação de dois fatores em sua conta). As solicitações carregam o ID do cliente e um token de portador juntos; esquecer o cabeçalho do Client ID é o mistério clássico 401.

Tokens de acesso ao aplicativo vem do fluxo de credenciais do clienteuma única solicitação de servidor para servidor com seu ID e segredo. Eles não têm nenhum usuário anexado e isso é bom, porque leituras públicas, perfis de usuário, transmissões ao vivo, jogos principais, clipes não precisam de contexto de usuário. Para a maioria das ferramentas somente leitura, esse é o único fluxo que você toca.

Tokens de acesso do usuário vêm do código de autorização ou dos fluxos de código do dispositivo, onde uma pessoa aprova seu aplicativo e concede escopos. Você só precisa deles quando estiver agindo em nome de alguém: lendo sua lista de assinantes, enviando mensagens de bate-papo em nome dessa pessoa, realizando ações de moderação. A regra prática: se sua ferramenta funcionar apenas olhando para Twitch, token de aplicativo; se fizer algo como usuário, token de usuário.

Os tokens expiram, portanto, os aplicativos reais os armazenam em cache com seu tempo de vida relatado e são atualizados em um 401, em vez de presumir que um token dura para sempre.

O que você pode ler

Um tour pelos endpoints que alimentam a maioria das ferramentas:

Usuários. Dê ao endpoint dos usuários um nome de usuário e ele retornará o registro público da conta: nome de exibição, imagem do perfil, descrição, status de Afiliado ou Parceiro e o carimbo de data/hora exato de criação da conta. Esse último campo é interessante porque o Twitch não o exibe em nenhum lugar de um perfil, mas é um dos sinais de confiança mais úteis da plataforma, os moderadores usam a idade da conta para identificar contas descartáveis ​​e os streamers a usam para filtrar entradas de brindes. A data de criação por si só alimenta uma pequena subcategoria de ferramentas: verificadores gratuitos de idade de contas, como Verificador de idade da conta Twitchsão essencialmente um endpoint com uma página limpa ao redor, pegando qualquer nome de usuário público e retornando a data de criação, idade, avatar e status da emissora. É uma boa ilustração de até onde pode ir um único campo Helix bem escolhido.

Fluxos. O endpoint do stream informa quem está ao vivo no momento, com títulos, categorias, URLs de miniaturas e contagens de espectadores. Esta é a espinha dorsal de todo notificador “é meu streamer ao vivo favorito” e de todo site estilo diretório, e pesquisá-lo ao longo do tempo é como histórico de visualização do gráfico de rastreadores de estatísticas.

Jogos e categorias. Principais jogos, pesquisa de categoria e metadados. Combinado com dados de fluxos, é assim que os sites de análise classificam as categorias e como as ferramentas respondem “quão lotada está esta categoria no momento”.

Clipes e vídeos. Metadados de clipes, contagens de visualizações e ferramentas de criação. Destaque compiladores e bots de compartilhamento de clipes ao vivo aqui.

Bate-papo e EventSub. A integração moderna de chat é executada por meio de assinaturas EventSub para eventos de mensagens, com um endpoint Helix para envio de mensagens. Os bots de moderação assinam os eventos de seu interesse e agem por meio da API com os escopos apropriados.

Limites de taxa e outras arestas nítidas

Helix impõe um limite de taxa baseado em pontos por ID do cliente, e cada resposta informa sua posição por meio dos cabeçalhos Ratelimit-Limit, Ratelimit-Remaining e Ratelimit-Reset. Ferramentas bem comportadas leem esses cabeçalhos e recuam antes de chegar a zero; aqueles mal comportados tentam novamente 429s em loop e se perguntam por que as coisas pioram. Para ferramentas de estilo de pesquisa, a solução prática é o armazenamento em cache. Dados como datas de criação de contas nunca mudam, portanto, não há motivo para perguntar duas vezes.

Mais algumas vantagens que vale a pena conhecer antes de morderem:

Os nomes de usuário mudam, os IDs não. Armazene IDs de usuário, não logins, ou seus dados salvos acabarão apontando para a pessoa errada.

Usuários ausentes não são erros. Procurar um nome de usuário inexistente retorna uma resposta bem-sucedida com uma matriz de dados vazia, portanto, lide explicitamente com o caso vazio.

O lote existe. O endpoint de usuários leva até 100 logins em uma chamada, o que importa no momento em que sua ferramenta verifica listas em vez de indivíduos.

Os segredos permanecem no lado do servidor. O segredo do cliente identifica seu aplicativo; chamar o endpoint do token a partir do código do navegador entrega a identidade do seu aplicativo a qualquer pessoa que abra o devtools. As ferramentas públicas colocam um pequeno servidor entre o navegador e o Twitch.

O ecossistema que ele criou

A razão pela qual o ecossistema de terceiros do Twitch é tão grande é que a barreira é tão baixa: uma API pública, acesso gratuito generoso e uma plataforma onde pequenas questões realmente importam para as pessoas. É por isso que o espaço está cheio de ferramentas restritas, cada uma respondendo bem a uma coisa, quando essa conta foi criada, esse canal está ao vivo, quão rápido essa categoria está crescendo, quais clipes surgiram esta semana. A maioria deles é um fim de semana de trabalho em um ou dois endpoints, e alguns deles se transformam em produtos reais.

Se você quiser começar, o caminho é curto: registre um aplicativo no console do desenvolvedor, solicite um token de acesso ao aplicativo e chame o endpoint de usuários ou fluxos por algo que você realmente gosta. A documentação oficial em dev.twitch.tv é atual e bem conservado, o que não é algo que toda plataforma possa reivindicar. Escolha um dado que o Twitch coleta, mas não exibe, coloque uma interface limpa nele e você estará seguindo a mesma receita da maioria das ferramentas do Twitch que você já usa.

Source link