Execute seus vídeos e transmissões ao vivo no seu próprio site pela API da DCAST

Se o seu produto já tem páginas, usuários e banco de dados próprios, mandar as pessoas para um painel de vídeo separado é um retrocesso. Você quer que o seu próprio código adicione vídeos, liste-os e inicie transmissões enquanto os visitantes continuam no seu site. Este artigo mostra como fazer essa configuração com a API da DCAST, as decisões a tomar primeiro e as falhas a verificar antes do lançamento.

Conecte o seu site à DCAST uma única vez pela API; depois disso, o seu próprio código adiciona novos vídeos e cria transmissões ao vivo, sem precisar visitar o painel da DCAST.

Mantenha a chave no seu servidor e decida quem é dono de quê

Antes de escrever qualquer código de upload, decida onde a chave da API fica. Mantenha a chave da API no seu servidor e nunca a coloque em uma página que os seus visitantes carregam. Qualquer pessoa que abra o código-fonte da página ou o registro de rede pode copiar uma chave enviada ao navegador e, a partir daí, agir como a sua conta. Guarde-a em uma variável de ambiente, mantenha-a fora do controle de versão e deixe o navegador falar apenas com rotas do seu próprio backend. Essas rotas devem verificar se o visitante tem permissão para enviar antes de chamar a API de vídeo.

Um vídeo adicionado pela API pertence à conta dona da chave da API. Se vários projetos compartilham uma única chave, todos os vídeos vão parar em uma só biblioteca e você não consegue saber de quem é cada conteúdo. Sempre que puder, use uma chave separada para cada projeto, para poder trocar uma sem quebrar as outras e para que um vazamento tenha alcance menor.

Envie um vídeo a partir do seu próprio código

Quando você adiciona um vídeo pela API, informa um título, um nome de arquivo, um tamanho de arquivo e uma visibilidade, como pública.

Cada requisição de upload devolve o endereço para o qual o seu site envia o arquivo de vídeo e um endereço de status que informa ao seu site quando o vídeo está pronto para ser exibido.

O arquivo em si é enviado ao endereço de upload devolvido com uma requisição PUT.

Decida quem envia os bytes. Enviar a partir do seu servidor é o caminho mais simples para registrar e repetir tentativas. Enviar direto do navegador do visitante poupa o seu backend de repassar arquivos grandes, mas então você precisa ter certeza de que o endereço de upload é seguro para ser exposto a esse visitante e precisa tratar o caso de uma aba que fecha no meio do envio. Escolha uma abordagem por projeto, anote por que a escolheu e teste com uma conexão limitada.

O espaço de armazenamento do arquivo é reservado para a sua conta no momento em que o upload é solicitado, antes de o primeiro byte do arquivo se mover.

Leia a resposta da requisição de upload antes de começar a enviar bytes e pare se for um erro. Empurrar um arquivo grande para um endereço que você nunca confirmou desperdiça o tempo do visitante e a sua banda. Mostre uma mensagem clara quando a requisição for recusada e evite tentar de novo em um laço rápido, o que só repete a mesma recusa.

Meça o tamanho do arquivo do seu lado e envie exatamente esse número. Uma divergência entre o tamanho declarado e o arquivo real é o tipo de bug que só aparece com uploads grandes; por isso, teste um arquivo pequeno e um arquivo de vários gigabytes antes de confiar no fluxo.

Espere pelo endereço de status antes de exibir um vídeo

O seu site não deve mostrar um player assim que o PUT termina. O endereço de status da requisição de upload é como o seu site descobre que o vídeo está pronto para ser exibido; portanto, guarde-o junto do registro do vídeo no seu próprio banco de dados.

Faça consultas com intervalos crescentes, por exemplo a cada poucos segundos no início e depois a cada trinta segundos, e pare após um limite razoável. Salve o último estado conhecido com um carimbo de data e hora, para que a reinicialização do servidor não faça você perder o rastro de um vídeo. Quando o limite passar, marque o vídeo como atrasado na sua interface em vez de mostrar um indicador de carregamento que nunca termina.

Cada vídeo da lista mostra o seu status, por exemplo pronto, junto com o endereço da sua página de player.

Use essa lista como rede de segurança. Uma tarefa noturna que compare o seu banco de dados com a lista detecta qualquer vídeo cuja verificação de status foi perdida, por exemplo porque o seu servidor estava fora do ar durante a espera. Corrija a divergência atualizando o seu próprio registro, não enviando o arquivo de novo.

Monte uma galeria a partir da sua biblioteca

O seu site lê a lista dos seus vídeos com o status de cada um e busca o código de player pronto de qualquer um deles, podendo assim montar a sua própria galeria de vídeos a partir da sua biblioteca da DCAST.

A lista dos seus vídeos contém apenas os vídeos da conta dona da chave, nunca os vídeos de outra conta.

A lista é paginada e informa o número total dos seus vídeos, de modo que o seu site pode percorrer uma biblioteca grande página por página.

Não busque a biblioteca inteira a cada visualização de página. Mantenha a lista em cache no seu servidor por pouco tempo, mostre aos visitantes apenas os vídeos com status pronto e use a contagem total para desenhar os links de página. Limpe o cache quando o seu próprio código adicionar um vídeo, para que o novo item apareça na hora.

Pedir o código de player de um vídeo que pertence a outra conta é respondido como não encontrado. Trate essa resposta como um caso comum no seu código. Quando ela aparecer para um identificador que você mesmo guardou, verifique primeiro qual chave o seu ambiente está usando, porque uma chave errada é uma causa mais provável do que uma indisponibilidade.

Coloque o player na sua página

O código do player vem como um endereço simples, como um trecho de iframe e como uma versão responsiva que se ajusta à página.

O código do player é um iframe que você coloca na sua própria página.

Escolha conforme o layout. Use a versão responsiva em páginas de artigos e grades de cartões, onde a largura muda com a tela. Use o endereço simples quando quiser montar o iframe você mesmo, por exemplo para adicionar um atributo title que ajude leitores de tela. Verifique a página em um celular de verdade antes do lançamento, porque um quadro de tamanho fixo é o motivo mais comum de um vídeo incorporado parecer quebrado no celular.

Você pode colocar o player dos seus vídeos e transmissões no seu próprio site com um código de incorporação curto.

Por padrão, o player incorporado funciona em qualquer site, de modo que um parceiro ou um fã pode compartilhar o seu conteúdo sem pedir antes a você.

Se quiser ter controle, liste os domínios em que o seu player pode aparecer, e todos os outros sites serão recusados.

Decida a lista pelo seu objetivo. Restrinja a lista quando você vende acesso pelo seu próprio site e quer que o player apareça apenas lá. Deixe a lista vazia quando o seu objetivo for alcance, porque assim cada cópia do código de incorporação funciona para quem a colar.

Inicie transmissões ao vivo a partir do seu código

O seu site cria uma transmissão ao vivo pela API e recebe os endereços para publicar, junto com o código do player para a página que exibe a transmissão.

Uma nova transmissão vem com um endereço RTMP, um endereço SRT e, onde estiver disponível, um endereço HTTPS para WHIP.

Uma transmissão ao vivo criada pela API é armazenada para a sua conta e tem o seu próprio endereço de incorporação para o player.

Escolha o endereço de publicação que corresponde ao seu encoder. O RTMP é aceito por quase todos os encoders de desktop e equipamentos de hardware, o SRT lida melhor com uma rede com perdas quando o seu encoder o suporta, e o WHIP permite que um navegador publique sem software extra. Se você não tem um motivo forte para escolher de outra forma, comece com RTMP e passe para os outros quando a sua primeira transmissão funcionar.

Antes de um evento real, faça um ensaio de dez minutos criado pelo mesmo caminho de código que você usará no dia. Verifique se o player na sua página mostra a imagem, se o som está presente e se o seu encoder se reconecta depois de você desligar a rede por alguns segundos. Depois guarde o identificador da transmissão para que a sua equipe de suporte possa encontrá-la mais tarde.

Faça estas verificações antes do lançamento

Percorra esta lista curta em ordem. Primeiro, procure a chave da API nas suas páginas geradas e no registro de rede do navegador; ela não deve aparecer em lugar nenhum. Segundo, envie um arquivo pequeno, um arquivo grande e um arquivo não suportado, e confirme que cada um termina em um estado que a sua interface consegue explicar. Terceiro, abra a galeria como um visitante sem login e verifique se os vídeos não concluídos estão ocultos. Quarto, peça um player para um identificador que não existe e confirme que a sua página se degrada com elegância em vez de mostrar um quadro vazio.

Quando essas verificações passarem, os seus visitantes veem um único site, o seu código é dono do fluxo de trabalho e a plataforma de vídeo fica em segundo plano. Comece com um upload e uma página de galeria, e depois adicione as transmissões quando a primeira parte funcionar sem sobressaltos.