Skeleton

O que é Skeleton?

Skeleton é uma ferramenta de linha de comando (CLI) projetada para facilitar o desenvolvimento de widgets na plataforma Kommo. Ele automatiza o processo de configuração, implantação e documentação, gerando uma estrutura básica de projeto (esqueleto) com React, TypeScript e outras tecnologias modernas.

  • Permite criar widgets personalizados rapidamente.
  • Inclui opções de digitação, documentação e localização.
  • Melhora a experiência do desenvolvedor, reduzindo bugs e o tempo de desenvolvimento.

Por que usar?

O Skeleton resolve os principais problemas que os desenvolvedores enfrentam ao trabalhar com widgets na Kommo:

  • Falta de documentação clara sobre os frameworks Moderna.
  • Dificuldade em configurar ambientes de desenvolvimento e implantar widgets.
  • Necessidade de personalização e escalabilidade.

Vantagens:

  • Acelera o desenvolvimento.
  • Melhora a qualidade do código.
  • Reduz erros.
  • Reduz a sobrecarga da equipe de suporte.

Lógica de trabalho

Passo 1: Execute npx @kommo-crm/create-integration no seu terminal (adicione as flags --project-name e --en/--es/--pt para pular prompts).

Passo 2: Se não estiver usando flags, escolha um idioma (inglês, espanhol ou português) quando solicitado.

Passo 3: Insira o nome do diretório do projeto. A CLI criará uma pasta para o seu widget.

Passo 4: Escolha a(s) localidade(s) necessária(s); a ferramenta criará /i18n com os arquivos JSON de tradução (en.json, es.json, etc.).

Passo 5: A CLI guia você pela configuração do manifesto: decida se o widget deve inicializar uma vez ou a cada carregamento de página, quais dados ele precisa (links, e-mails) e quais locais no aplicativo Kommo ele suportará. Ela solicitará quaisquer campos extras obrigatórios.

Essas prompts interativas garantem que a configuração e o manifesto do seu widget estejam configurados corretamente.

Lista de Locais

Esta tabela lista todos os locais onde um widget pode estar dentro da Kommo:

List of locations
list of locationsNomes possíveis na lista
lcard-1O widget está no painel direito do perfil de um lead
lcard-0O widget está inicializado no perfil de um lead
ccard-1O widget está no painel direito do perfil de um contato
ccard-0O widget está inicializado no perfil de um contato
comcard-1O widget está no painel direito do perfil da empresa
comcard-0O widget está inicializado no perfil da empresa
llist-1O widget está disponível no menu da lista de leads
llist-0O widget está inicializado na lista de leads
clist-1O widget está disponível no menu da lista de contatos
clist-0O widget está inicializado na lista de contatos
tlist-1O widget está disponível no menu da lista de tarefas
tlist-0O widget é inicializado na lista de tarefas
settingsJanela de configurações do widget
advanced_settingsPágina do widget nas configurações avançadas
card_sdkWidget dentro do card via SDK.
catalogsWidget na lista de catálogos
digital_pipelineWidget nas configurações de automação (Funil de vendas)
lead_sourcesWidget nas fontes de leads
widget_pageWidget no menu à esquerda (integrações públicas). Veja mais: Barra de menu à esquerda
smsSMS
mobile_card ***Aplicativo móvel
salesbot_designerÁrea de design do Salesbot
website_chat_buttonBotão de chat do site
everywhereEm todos os lugares

O array locations em manifest.json determina onde — e como — os usuários verão seu widget.

Propriedades extras para o Manifesto

Esta tabela mapeia cada local específico para o bloco JSON que você deve adicionar em manifest.json:

Local

Propriedades adicionais no Manifesto

Descrição

Pipeline digital

"dp": { "action_multiple": false, "webhook_url": "https://example.com/webhook"

Controla ações de vários elementos e define o endpoint do webhook que a Kommo chamará

Configurações avançadas

"advanced": { "title": "advanced.title" }

Precisa apenas do título da aba que aparece nas Configurações avançadas

Aplicativo móvel

"mobile": { "frame_url": "https://example.com/", "color": "#ffff00" }

URL carregada dentro do aplicativo móvel da Kommo, além da cor do cabeçalho

SMS

"sms": { "endpoint": "https://example.com/sms_endpoint" }

O endpoint que a Kommo acessará ao enviar SMS

❗️

Inclua apenas os blocos que correspondem aos locais selecionados — caso contrário, a Kommo rejeitará o manifesto

Estrutura do projeto

Digitação em TypeScript::

  • Métodos do ciclo de vida do widget (init(), render(), settings()...)
  • Métodos internos (get_settings(), etc.)
  • Variável APP para interagir com a API da Kommo

Habilitando o Modo de Desenvolvimento após o Upload do Arquivo do Widget

Etapa 1: Configurar o Ambiente

Antes de iniciar o desenvolvimento ou a compilação do widget de produção, preencha as variáveis ​​de ambiente necessárias. O projeto inclui dois arquivos de ambiente predefinidos:

  • .dev.env — usado no desenvolvimento
  • .prod.env — usado durante a compilação de produção

Atualize esses arquivos com os valores apropriados.

Importante! Nunca envie esses arquivos com segredos reais para o controle de versão. Use o gerenciamento de segredos específico do ambiente em CI/CD para implantação.

Etapa 2: Desenvolvimento

Opção A: Com Docker e Make

Gere um pacote ZIP pronto para produção:

make build

Opção B: Localmente com yarn

Você também pode compilar sem o Docker:

yarn install
yarn run build

Isso criará uma pasta dist com seu script de compilação, manifesto etc. e zip.

Etapa 3: Compilar

Opção A: Com Docker

Ative o servidor de desenvolvimento com um comando:

make run-dev

Opção B: Localmente com yarn

Você também pode executar o servidor de desenvolvimento sem o Docker:

yarn install
yarn run dev

Etapa 4: Habilitando o Modo de Desenvolvimento Após o Upload do Arquivo do Widget

Para habilitar o modo de desenvolvimento após o upload do arquivo widget.zip, siga estes passos:

  1. Certifique-se de que a porta e o código do widget corretos estejam definidos em suas variáveis ​​de ambiente. Nos seus arquivos .dev.env e .prod.env, certifique-se de que os seguintes itens estejam configurados corretamente:
  2. LOCALHOST_PORT — Deve corresponder à porta em que seu servidor de desenvolvimento local está sendo executado (por exemplo, 9000).
  3. INTEGRATION_CODE — Este deve ser o código específico do seu widget. Você pode encontrá-lo na aba Chave e Escopos após criar uma integração.
  4. Habilite o modo de desenvolvimento adicionando o seguinte a localStorage no navegador do cliente. Você pode fazer isso abrindo o console do desenvolvedor do navegador e digitando o seguinte comando:
localStorage.setItem('your_widget_code_is_dev', '9000');

Use a mesma porta que LOCALHOST_PORT e o mesmo código de widget que INTEGRATION_CODE nos arquivos .env.

Alternativamente, você pode adicionar manualmente a entrada localStorage no armazenamento do navegador, se necessário.

Uma vez feito isso, o widget carregará recursos do seu servidor de desenvolvimento local quando estiver no modo de desenvolvimento, permitindo que você teste sem precisar reenviar o arquivo do widget todas as vezes que fizer uma mudança."

Referências