Pular para o conteúdo principal

Introdução

Para desenvolver e hospedar um aplicativo no Square Cloud, é essencial seguir uma sequência estruturada de configurações e pré-requisitos. Este guia técnico abordará todo o processo, desde a configuração inicial até a implantação em produção.

Pré-requisitos

  • Conta Square Cloud: Plataforma de hospedagem para seu aplicativo. Cadastre-se através da página de cadastro usando seu e-mail.
  • Plano Pago Ativo: Garante recursos dedicados e desempenho otimizado para seu aplicativo. Confira nossos planos disponíveis e escolha o mais adequado às suas necessidades.
Está se perguntando quanta RAM e CPU seu plano precisa para hospedar Bots do X (Twitter)?
Não se preocupe, estamos aqui para ajudar. Nosso plano Hobby oferece 2GB de RAM e 2vCPU, o que deve ser suficiente para a maioria dos Bots do X (Twitter). No entanto, se você estiver trabalhando em um projeto maior e precisar de mais estabilidade, recomendamos considerar nosso plano Pro. Com recursos adicionais, você pode manter a estabilidade mesmo durante picos de demanda. Para comprar, basta clicar aqui.

Criando o projeto

Uma conta ativa no X (Twitter) é necessária para autenticação e operação do bot. Se você não tem uma, inscreva-se no site oficial do X. Uma conta de Desenvolvedor X também é necessária para acessar as APIs. Solicite acesso através do Portal do Desenvolvedor X.

Aplicação de Bot no X

1

Acessando o Portal do Desenvolvedor

  1. Acesse o Portal do Desenvolvedor X.
  2. Faça login com sua conta X (Twitter).
  3. Se for sua primeira vez, complete o processo de solicitação de acesso de desenvolvedor.
2

Criação do Projeto

  1. No painel, clique em “Create Project” (Criar Projeto).
  2. Escolha um nome para seu projeto (ex: “Square Cloud Bot”).
  3. Selecione o caso de uso mais apropriado (ex: “Making a bot” - Criando um bot).
  4. Forneça uma descrição detalhada do seu bot.
  5. Confirme a criação do projeto.
3

Configuração do Aplicativo

  1. Dentro do projeto criado, clique em “Create App” (Criar Aplicativo).
  2. Defina um nome exclusivo para seu aplicativo.
  3. Confirme a criação do aplicativo.
  4. Anote o App ID gerado para referência futura.
4

Geração das Chaves de API

  1. Navegue até a seção “Keys and tokens” (Chaves e tokens) do seu aplicativo.
  2. Na seção “Consumer Keys” (Chaves de Consumidor), clique em “Regenerate” (Regerar) para gerar:
    • API Key (Chave de Consumidor)
    • API Secret Key (Chave Secreta de Consumidor)
  3. Importante: Copie e salve estas chaves imediatamente, pois você não poderá visualizá-las novamente.
5

Configuração de Permissões

  1. Vá para a seção “App permissions” (Permissões do App).
  2. Clique em “Edit” (Editar) para modificar as permissões.
  3. Selecione “Read and write” (Leitura e escrita) para permitir que seu bot publique tweets.
  4. Se necessário, selecione “Read and write and Direct message” (Leitura, escrita e Mensagem direta) para funcionalidade de DM.
  5. Salve as alterações.
6

Geração dos Tokens de Acesso

  1. Retorne à seção “Keys and tokens”.
  2. Na seção “Access Token and Secret” (Token e Segredo de Acesso), clique em “Generate” (Gerar).
  3. Confirme a geração do token.
  4. Copie e salve:
    • Access Token (Token de Acesso)
    • Access Token Secret (Segredo do Token de Acesso)
  5. Aviso: Estes tokens não podem ser visualizados novamente após fechar a página.
7

Verificação de Credenciais

  1. Confirme que você possui todas as 4 credenciais necessárias:
    • API Key (Chave de Consumidor)
    • API Secret Key (Chave Secreta de Consumidor)
    • Access Token (Token de Acesso)
    • Access Token Secret (Segredo do Token de Acesso)
  2. Armazene essas credenciais em um local seguro
  3. Importante: Nunca compartilhe ou exponha estas credenciais publicamente

Desenvolvendo o projeto

  1. Verificação do Node.js: Verifique se o Node.js está instalado em seu sistema. Caso contrário, baixe-o no site oficial do Node.js.
  2. Inicialização do projeto: Crie um novo projeto Node.js executando:
Terminal
npm init -y
  1. Instalação de dependências: Instale as bibliotecas necessárias para o bot:
Terminal
npm install twitter-api-v2
  1. Configuração de variáveis de ambiente: Crie um arquivo .env para armazenar suas credenciais de forma segura (este arquivo não será usado na Square Cloud, mas é uma boa prática local):
.env
API_KEY=sua_api_key_aqui
API_SECRET_KEY=sua_api_secret_key_aqui
ACCESS_TOKEN=seu_access_token_aqui
ACCESS_TOKEN_SECRET=seu_access_token_secret_aqui
  1. Criação do arquivo principal: Desenvolva o arquivo index.js com a estrutura base do bot:
index.js
// Importa módulos necessários
const { TwitterApi } = require('twitter-api-v2');

// Configure o cliente Twitter com autenticação
const client = new TwitterApi({
  appKey: process.env.API_KEY,
  appSecret: process.env.API_SECRET_KEY,
  accessToken: process.env.ACCESS_TOKEN,
  accessSecret: process.env.ACCESS_TOKEN_SECRET,
});

// Cliente com permissões de leitura e escrita
const rwClient = client.readWrite;

// Função para verificar se o bot está funcionando
async function verifyBot() {
  try {
    // Obtém informações do usuário autenticado
    const user = await rwClient.currentUser();
    console.log(`Bot inicializado com sucesso! Usuário: @${user.screen_name}`);
    return true;
  } catch (error) {
    console.error('Erro ao verificar o bot:', error);
    return false;
  }
}

// Função para postar um tweet
async function postTweet(text) {
  try {
    const tweet = await rwClient.tweet(text);
    console.log(`Tweet publicado com sucesso! ID: ${tweet.data.id}`);
    return tweet;
  } catch (error) {
    console.error('Erro ao postar tweet:', error);
    throw error;
  }
}

// Função para responder a menções
async function respondToMentions() {
  try {
    // Busca menções recentes
    const mentions = await rwClient.userMentionTimeline({
      count: 10,
      result_type: 'recent'
    });
    
    for (const tweet of mentions.data) {
      // Verifica se é uma menção nova (implementar lógica de controle)
      if (tweet.text.includes('!ping')) {
        // Responde à menção
        await rwClient.reply(
          'Pong! 🤖 Bot do X funcionando corretamente!',
          tweet.id
        );
        console.log(`Respondeu à menção de @${tweet.user.screen_name}`);
      }
    }
  } catch (error) {
    console.error('Erro ao processar menções:', error);
  }
}

// Função para buscar e interagir com tweets específicos
async function searchAndInteract(query) {
  try {
    // Busca tweets com uma query específica
    const tweets = await rwClient.search(query, {
      count: 5,
      result_type: 'recent'
    });
    
    for (const tweet of tweets.statuses) {
      // Curte o tweet
      await rwClient.like(tweet.id_str);
      console.log(`Curtiu o tweet de @${tweet.user.screen_name}`);
      
      // Espera um pouco entre as ações para evitar rate limiting
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  } catch (error) {
    console.error('Erro ao buscar e interagir:', error);
  }
}

// Função principal do bot
async function runBot() {
  console.log('Iniciando bot X...');
  
  // Verifica se o bot está configurado corretamente
  const botOk = await verifyBot();
  if (!botOk) {
    console.error('A inicialização do bot falhou');
    return;
  }
  
  // Exemplo: Postar um tweet de inicialização
  try {
    await postTweet('🤖 Bot do X inicializado e rodando na Square Cloud!');
  } catch (error) {
    console.log('Tweet de inicialização falhou, mas o bot continua rodando');
  }
  
  // Loop principal do bot
  setInterval(async () => {
    try {
      // Verifica e responde a menções a cada 5 minutos
      await respondToMentions();
      
      // Exemplo: Busca e interage com tweets sobre um tópico específico
      // await searchAndInteract('#SquareCloud');
      
    } catch (error) {
      console.error('Erro no loop principal:', error);
    }
  }, 5 * 60 * 1000); // 5 minutos
  
  console.log('Bot rodando. Pressione Ctrl+C para parar.');
}

// Manipulação de sinal para encerramento elegante
process.on('SIGINT', () => {
  console.log('\nEncerrando bot X...');
  process.exit(0);
});

process.on('SIGTERM', () => {
  console.log('\nEncerrando bot X...');
  process.exit(0);
});

// Inicializa o bot
runBot();

Realizando o Deploy

Após preparar os arquivos do seu projeto, você pode enviá-los para a Square Cloud e hospedar seu projeto. Para fazer isso, crie um arquivo ZIP contendo todos os arquivos do seu projeto.
Segurança: Nunca inclua suas credenciais de API diretamente no código. Sempre use variáveis de ambiente na Square Cloud.
Na Square Cloud, configure as seguintes variáveis de ambiente através do painel de controle:
  • API_KEY: Sua chave de API do X
  • API_SECRET_KEY: Sua chave secreta de API do X
  • ACCESS_TOKEN: Seu token de acesso
  • ACCESS_TOKEN_SECRET: Seu segredo do token de acesso

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

Finally, click on the "Deploy" button to host your project on Square Cloud.
After deployment, you can monitor your project's status and logs from the dashboard.

Via CLI

Para usar esse método, você precisa criar um arquivo de configuração chamado squarecloud.app no diretório raiz do seu projeto. Esse arquivo conterá a configuração necessária para o seu projeto.

Saiba mais sobre: Como criar arquivo de configuração da Square Cloud.

O arquivo squarecloud.app é um arquivo de configuração que será usado para configurar seu aplicativo; ele será usado para definir seu ambiente.
1

Primeiro Passo

Primeiro, você precisa ter a CLI instalada em seu ambiente. Se você ainda não a possui, execute o seguinte comando em seu terminal:
npm install -g @squarecloud/cli
Se você já a possui, recomendamos atualizá-la. Para fazer isso, execute o seguinte comando em seu terminal:
squarecloud update
2

Segundo Passo

Agora, para autenticar e usar outros comandos da CLI, você encontrará sua chave de autorização aqui clicando em "Solicitar Chave da API". Após obter sua chave de autorização, execute o seguinte comando:
squarecloud auth login
3

Terceiro Passo

Finalmente, para fazer o deploy da sua aplicação para a Square Cloud usando a CLI, você precisa executar o seguinte comando:
squarecloud upload
Ou se já possui o zip criado:
squarecloud upload --file <caminho/para/zip>

Recursos Adicionais

Para aprofundar seu conhecimento sobre o desenvolvimento de bots do X usando twitter-api-v2, consulte a documentação oficial da biblioteca twitter-api-v2. A documentação fornece guias detalhados, tutoriais avançados e referências completas de API para maximizar sua implementação. Veja também:

Monitoramento de Hashtags

// Função para monitorar hashtags específicas
async function monitorHashtags(hashtags) {
  for (const hashtag of hashtags) {
    try {
      const tweets = await rwClient.search(`#${hashtag}`, {
        count: 5,
        result_type: 'recent'
      });
      
      // Processa os tweets encontrados
      for (const tweet of tweets.statuses) {
        console.log(`Tweet encontrado com #${hashtag}: ${tweet.text}`);
        // Implementar lógica de interação
      }
    } catch (error) {
      console.error(`Erro ao monitorar #${hashtag}:`, error);
    }
  }
}

Postagens Agendadas

// Função para agendar postagens
function schedulePost(text, delay) {
  setTimeout(async () => {
    try {
      await postTweet(text);
      console.log('Postagem agendada publicada com sucesso!');
    } catch (error) {
      console.error('Erro ao publicar postagem agendada:', error);
    }
  }, delay);
}

// Exemplo: Agendar uma postagem para 1 hora
schedulePost('🤖 Postagem agendada pelo bot!', 60 * 60 * 1000);

Limitação de Taxa (Rate Limiting)

O X (Twitter) possui limites de taxa rigorosos. Implemente controles para evitar exceder esses limites:
// Controle de Limitação de Taxa
const rateLimiter = {
  lastRequest: 0,
  minInterval: 1000, // 1 segundo entre as requisições
  
  async wait() {
    const now = Date.now();
    const timeSinceLastRequest = now - this.lastRequest;
    
    if (timeSinceLastRequest < this.minInterval) {
      const waitTime = this.minInterval - timeSinceLastRequest;
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }
    
    this.lastRequest = Date.now();
  }
};

Tratamento de Erros

// Função auxiliar para tentar novamente uma operação em caso de falha
async function retryOperation(operation, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      console.error(`Tentativa ${i + 1} falhou:`, error.message);
      
      if (i === maxRetries - 1) {
        throw error;
      }
      
      // Espera antes de tentar novamente
      await new Promise(resolve => setTimeout(resolve, 2000 * (i + 1)));
    }
  }
}

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.