Skip to main content

Introdução

  • Este guia supõe que você tenha um bot aprovado no top.gg e esteja usando Node.js ou Python em seu projeto.
  • Em seguida, crie uma conta na Square Cloud através da página de cadastro. Você pode usar seu e-mail para se registrar.
  • Por fim, é necessário ter um plano ativo na sua conta. Compare os planos disponíveis e escolha um conforme a sua necessidade.

Configurando o ambiente

  1. Antes de começar, verifique se você tem o Node.js e o npm instalados em seu sistema. Caso contrário, faça o download no site oficial do Node.js.
  2. Inicie um novo projeto Node.js e habilite a sintaxe import com os comandos:
Terminal
Esses comandos criam um arquivo package.json no diretório atual.
  1. Instale o Express:
Terminal

Configurando o projeto

1. Obtenha o secret do webhook:
  • Escolha o subdomínio que sua aplicação vai usar na Square Cloud (o campo SUBDOMAIN do seu arquivo de configuração), por exemplo mysite. A URL do seu webhook será então https://mysite.squareweb.app/topgg.
  • No Top.gg, abra o dashboard do seu projeto e vá em Webhooks.
  • Cole a URL do webhook e salve. O Top.gg então gera um secret de webhook que começa com whs_: copie-o e mantenha-o privado. Seu código o lê da variável de ambiente TOPGG_WEBHOOK_SECRET.
O Top.gg assina cada requisição com o header x-topgg-signature, no formato t=<timestamp>,v1=<signature>, em que a assinatura é um HMAC SHA-256 de <timestamp>.<raw body> gerado com o seu secret. O código abaixo recalcula essa assinatura e rejeita qualquer requisição que não bata, assim ninguém mais consegue enviar votos falsos para a sua URL. Veja a documentação de webhooks do Top.gg para mais detalhes.
Este guia usa os webhooks v1 do Top.gg. O webhook legado v0, que envia uma senha no header Authorization com um payload diferente, não é abordado aqui.
2. Implemente o listener do webhook: As seções abaixo trazem exemplos de código em JavaScript e em Python:
O exemplo verifica a assinatura com o módulo nativo crypto do Node, então nenhum pacote do Top.gg é necessário. A classe Webhook do @top-gg/sdk 4.0.0 não é usada: nos nossos testes, o listener dela respondia entregas válidas com um erro de timeout, o que faz o Top.gg reenviá-las.
index.js

Criando o arquivo de configuração da Square Cloud

Crie um arquivo squarecloud.app na pasta do seu projeto. Defina SUBDOMAIN com o subdomínio que você escolheu no passo 1:
O SUBDOMAIN publica o listener em https://mysite.squareweb.app, e aplicações web precisam de pelo menos MEMORY=512. O código escuta na porta da variável de ambiente PORT, que a Square Cloud define como 80, e no host 0.0.0.0.

Aprenda como: criar o arquivo de configuração para a Square Cloud.

O arquivo squarecloud.app é usado para definir nome, descrição, versão, arquivo principal e outras configurações da sua aplicação.

Enviando sua aplicação para a Square Cloud

Após seguir todos os passos, a pasta do seu projeto deve conter o seu código, o arquivo de dependências (package.json ou requirements.txt) e o arquivo de configuração. Para enviar pelo dashboard, coloque-os em um arquivo .zip. Se a sua aplicação é um projeto Node.js, dê uma olhada no nosso artigo sobre Node.js. Se a sua aplicação é um projeto Python, dê uma olhada no nosso artigo sobre Python.

Via dashboard

1

Acesse a página de upload

Acesse a página de upload e envie seu arquivo zip.
2

Configure seu ambiente

Após fazer o upload do seu arquivo zip, você precisará configurar o nome, o arquivo principal ou o ambiente de execução e outras configurações do seu projeto.
Se você estiver enviando um projeto web, certifique-se de selecionar “Publicação na Web” e definir um subdomínio para o seu projeto.
3

Faça o deploy do projeto

Por fim, clique no botão “Deploy” para hospedar seu projeto na Square Cloud. Após o deploy, você poderá monitorar o status e os registros do seu projeto no dashboard.
Enviando aplicação para a Square Cloud
4

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. No dashboard, aguarde o status da sua aplicação mudar para em execução e verifique os registros em busca de erros de inicialização.
Se você fez deploy de um site ou API, abra https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.
Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

Via CLI

Para usar esse método, seu projeto precisa de um arquivo de configuração chamado squarecloud.app na raiz. Ele informa à Square Cloud como executar a sua aplicação.

Guia do arquivo de configuração

Saiba como criar o arquivo de configuração squarecloud.app que define o ambiente da sua aplicação.
1

Instale a CLI

Instale a CLI da Square Cloud. Se você já a tem, execute o mesmo comando para atualizá-la:
2

Faça login

Execute o comando abaixo. Ele abre o seu navegador: aprove o login lá e a CLI está pronta. Não há nenhuma chave de API para copiar. Para scripts e CI, veja autenticação da CLI.
3

Envie o seu projeto

Na pasta do seu projeto, execute o comando abaixo. A CLI compacta a pasta atual, deixando de fora o que o squarecloud.ignore lista, e faz o upload:
Para enviar um zip que você mesmo criou, passe-o com --file:
4

Confirme que seu app está no ar

Seu primeiro deploy geralmente leva menos de um minuto. Verifique o status e os registros da sua aplicação diretamente pelo terminal:
Se você fez deploy de um site ou API, abra https://<seu-subdominio>.squareweb.app no navegador: você deve ver sua aplicação respondendo. Se você fez deploy de um bot, envie um comando para confirmar que ele está online.
Seu app não está iniciando? Veja o guia de solução de problemas para as causas e correções mais comuns.

Definindo o secret do webhook

Adicione o seu secret whs_ como a variável de ambiente TOPGG_WEBHOOK_SECRET da sua aplicação, de uma destas formas:
  • Dashboard: na página de upload, abra Configuração avançada e adicione a variável antes do deploy. Para uma aplicação que já está no ar, adicione-a na página Variáveis de ambiente dela.
  • CLI: a partir da pasta do projeto, defina-a com squarecloud app env set e reinicie a aplicação:
A aplicação lê as variáveis de ambiente quando inicia, então reinicie-a após cada alteração. Enquanto o secret não estiver definido, o código rejeita todas as requisições com 401 Unauthorized. Veja Variáveis de ambiente para as outras formas de gerenciá-las.

Iniciando os testes

Se você fez tudo corretamente, abra https://mysite.squareweb.app/topgg no navegador (troque mysite pelo seu subdomínio). Se aparecer “Cannot GET /topgg” (Node.js) ou “Method Not Allowed” (Python), está tudo certo: a rota só aceita as requisições POST que o Top.gg envia.
  • No código JavaScript que criamos com app.post("/topgg", ...), a rota que vai receber os votos é “/topgg”. Então, se o seu site é mysite.squareweb.app, a URL do webhook é https://mysite.squareweb.app/topgg.
  • No código Python que criamos com @app.route("/topgg", methods=["POST"]), a rota que vai receber os votos também é “/topgg”. Então, a URL do webhook é a mesma https://mysite.squareweb.app/topgg.
Por fim, volte à página Webhooks do seu projeto no Top.gg e clique no botão “Send Test”. Depois, verifique os logs da sua aplicação. Se tudo deu certo, a mensagem que você definiu no console.log ou no print deve aparecer nos logs.
Exemplo de envio de teste do webhook do Top.gg
E assim, se tudo foi configurado corretamente, seu webhook estará pronto para enviar notificações quando o seu bot receber um voto no top.gg.

Solução de problemas

Domínio personalizado

Para usar um domínio personalizado (ex.: meusite.com) no lugar da URL padrão meusite.squareweb.app, você precisa do plano Standard ou superior. A URL padrão vem do campo SUBDOMAIN no arquivo de configuração. Para conectar o seu domínio, veja como configurar seu próprio domínio.

Requisitos mínimos de RAM

Mínimo: 512MB de RAM para sites e APIs, o suficiente para um build estático no runtime estático. Para aplicações que renderizam páginas no servidor (Next.js, Nuxt, Angular SSR e similares), recomendamos pelo menos 1GB de RAM. Para aplicações maiores, aloque mais RAM para evitar que a aplicação fique sem memória e trave.

Não foi possível encontrar esse site.

Verifique se o subdomínio/domínio corresponde ao configurado no campo SUBDOMAIN ou nas configurações de domínio personalizado. Se você acabou de enviar o site, aguarde até 60 segundos para a Square liberar o primeiro acesso.

Site demorou demais para responder…

O seu servidor precisa escutar na porta 80 e no host 0.0.0.0. A Square Cloud define as variáveis de ambiente PORT (80) e HOST (0.0.0.0) na sua aplicação: leia essas variáveis no código em vez de fixar outros valores. Um servidor que escuta apenas em localhost ou 127.0.0.1 nunca recebe requisições.

Próximos passos

Bot do Discord

Hospede o bot que recebe os votos.

Variáveis de ambiente

Gerencie o secret do webhook e outros segredos.

A aplicação não inicia

Corrija conflitos de porta, módulos faltando e outras falhas na inicialização.

Contate-nos

Se você continuar enfrentando dificuldades técnicas, nossa equipe de suporte especializada está disponível para auxiliá-lo. Entre em contato conosco e teremos prazer em ajudá-lo a resolver qualquer questão: a qualidade do suporte é uma grande parte do motivo pelo qual desenvolvedores avaliam a Square Cloud com 4,9/5 em 402 avaliações no Google e Trustpilot.