Pular para o conteúdo principal

Empacotamento e Implantação

Empacotamento para Implantação​

Quando seu app estiver pronto, você precisa empacotá-lo em um arquivo .zip para fazer o upload. O arquivo ZIP deve seguir convenções específicas de estrutura e incluir um arquivo manifest.json obrigatório.

O Arquivo manifest.json (Obrigatório)​

Todos os apps devem incluir um arquivo manifest.json no diretório assets/. Este arquivo contém os metadados do seu app:

{
  "app": {
    "type": "lua",
    "name": "my-app",
    "title": "My App",
    "version": "1.0.0",
    "description": "Uma breve descrição do que seu app faz",
    "dependencies": [
      {
        "name": "other-app",
        "version": ">=1.0.0"
      }
    ]
  },
  "contact_fields": [
    {
      "type": "STRING",
      "name": "customer_id",
      "display": "ID do Cliente",
      "private": false
    }
  ],
  "journeys": [
    {
      "name": "Jornada de Boas-vindas",
      "file": "journeys/welcome.md",
      "description": "Dá boas-vindas a novos usuários"
    }
  ],
  "media_assets": [
    {
      "asset_path": "images/logo.png",
      "filename": "logo.png",
      "content_type": "image/png",
      "description": "Logotipo da empresa"
    }
  ]
}

Metadados do App (Obrigatório)​

Campos obrigatórios:

  • app.type: O tipo do app (ex: "lua" para apps Lua)
  • app.name: O nome do seu app (deve corresponder ao nome do arquivo Lua principal sem extensão)
  • app.title: O título de exibição para seu app (mostrado na UI da Turn)
  • app.version: String de versão semântica (ex: 1.0.0, 2.1.3, 1.0.0-beta)
  • app.description: Uma breve descrição da funcionalidade do seu app

Campos opcionais:

  • app.dependencies: Um array de apps que devem estar instalados para que seu app funcione. Cada dependência deve especificar:
    • name: O nome exato do app requerido
    • version: Uma restrição de versão (ex: >=1.0.0, ~>2.1, 1.0.0)

Comportamento de dependências:

  • Se dependencies não for especificado ou for um array vazio [], a plataforma assume que seu app não tem dependências e pode ser instalado independentemente
  • Quando dependências são especificadas, a plataforma valida que todos os apps requeridos estão instalados com versões compatíveis antes de permitir a instalação
  • Entradas de dependência inválidas (sem name ou version) são silenciosamente ignoradas

Campos de Contato (Opcional)​

O array contact_fields define campos personalizados que seu app adicionará aos contatos. Esses campos são criados automaticamente quando o app é instalado usando turn.manifest.install().

"contact_fields": [
  {
    "type": "STRING",
    "name": "customer_id",
    "display": "ID do Cliente",
    "private": false
  },
  {
    "type": "BOOLEAN",
    "name": "is_premium",
    "display": "Membro Premium",
    "private": false
  },
  {
    "type": "NUMBER",
    "name": "loyalty_points",
    "display": "Pontos de Fidelidade",
    "private": true
  }
]

Propriedades do campo:

  • type (obrigatório): Tipo do campo - "STRING", "BOOLEAN", "NUMBER", ou "DATE"
  • name (obrigatório): Nome interno do campo (minúsculas, sublinhados permitidos)
  • display (obrigatório): Rótulo legível mostrado na UI
  • private (obrigatório): true para ocultar de usuários não-admin, false para mostrar a todos

Notas:

  • Campos são criados automaticamente durante a instalação do app
  • Campos podem ser inscritos para notificações de mudança usando turn.app.set_contact_subscriptions()
  • Use private: true para dados sensíveis como registros médicos, informações financeiras ou identificadores pessoais

Jornadas (Opcional)​

O array journeys define templates de jornada que seu app fornece. Estes são arquivos markdown no seu diretório assets/ que definem fluxos de conversação.

"journeys": [
  {
    "name": "Jornada de Boas-vindas",
    "file": "journeys/welcome.md",
    "description": "Dá boas-vindas a novos usuários e coleta informações básicas"
  },
  {
    "name": "Fluxo de Pagamento",
    "file": "journeys/payment.md",
    "description": "Processa pagamentos com integração Stripe"
  }
]

Propriedades da jornada:

  • name (obrigatório): Nome de exibição para a jornada na UI da Turn
  • file (obrigatório): Caminho para o arquivo markdown dentro do diretório assets/
  • description (obrigatório): Breve descrição do que a jornada faz

Notas:

  • Arquivos de jornada são importados automaticamente durante a instalação ao usar turn.manifest.install()
  • Jornadas podem chamar de volta para seu app usando a função DSL app()
  • Arquivos markdown de jornadas suportam a sintaxe DSL completa de jornadas da Turn.io

Ativos de Mídia (Opcional)​

O array media_assets define imagens e outros arquivos de mídia incluídos com seu app. Estes são enviados e disponibilizados para uso em jornadas e mensagens.

"media_assets": [
  {
    "asset_path": "images/welcome-banner.jpg",
    "filename": "welcome-banner.jpg",
    "content_type": "image/jpeg",
    "description": "Imagem de banner de boas-vindas"
  },
  {
    "asset_path": "images/logo.png",
    "filename": "logo.png",
    "content_type": "image/png",
    "description": "Logotipo da empresa"
  },
  {
    "asset_path": "documents/terms.pdf",
    "filename": "termos-de-servico.pdf",
    "content_type": "application/pdf",
    "description": "Documento de termos de serviço"
  }
]

Propriedades do ativo de mídia:

  • asset_path (obrigatório): Caminho para o arquivo dentro do diretório assets/ do seu app
  • filename (obrigatório): Nome a usar ao fazer upload (pode ser diferente de asset_path)
  • content_type (obrigatório): Tipo MIME (ex: "image/jpeg", "image/png", "application/pdf")
  • description (obrigatório): Descrição do propósito do ativo

Tipos de conteúdo suportados:

  • Imagens: image/jpeg, image/png, image/gif, image/webp
  • Documentos: application/pdf
  • Vídeos: video/mp4, video/3gpp
  • Áudio: audio/mpeg, audio/ogg, audio/aac

Notas:

  • Arquivos de mídia são enviados para o armazenamento de mídia da Turn durante a instalação
  • Arquivos enviados recebem URLs únicas que podem ser usadas em mensagens e jornadas
  • Use turn.assets.read() para acessar o conteúdo binário de ativos para upload

Sem o arquivo manifest.json, o upload do seu app falhará com um erro :manifest_not_found.

Estrutura do Arquivo ZIP​

Seu app deve seguir esta estrutura:

my-app.zip
├── my-app.lua           # Arquivo principal (obrigatório, deve corresponder ao nome do app)
├── my-app/              # Opcional: Diretório de módulos
│   ├── utils.lua
│   ├── handlers.lua
│   └── api/
│       └── client.lua
└── assets/              # Obrigatório: Contém manifest e arquivos estáticos
    ├── manifest.json    # OBRIGATÓRIO: Metadados do app
    ├── templates/
    │   └── welcome.md
    └── images/
        └── logo.png

Importante: O diretório assets/ agora é obrigatório (não opcional) já que deve conter o arquivo manifest.json.

Usando o Docker SDK (Recomendado)​

Se você usou o Docker SDK para criar o scaffold do seu app, o empacotamento é simples:

make build

# Isso cria my_app-0.0.1.zip (versão do manifest.json)

O comando build automaticamente:

  • Inclui seu arquivo .lua principal
  • Inclui o diretório assets/ com manifest.json
  • Inclui quaisquer módulos no diretório lib/
  • Exclui arquivos de teste e arquivos de desenvolvimento

Usando o Script Zip-It​

O template tradicional inclui um script zip-it.sh que automatiza o empacotamento:

./zip-it.sh

# O script irá remover quaisquer arquivos zip antigos,
# criar um novo arquivo zip com seu código mais recente

Empacotamento Manual​

Se você precisar de mais controle sobre o empacotamento:

# App simples (arquivo único)
zip payment-processor-1.0.0.zip payment-processor.lua

# App com módulos
zip -r my-app-1.0.0.zip my-app.lua my-app/

# App com ativos
zip -r my-app-1.0.0.zip my-app.lua my-app/ assets/

# Excluir arquivos de teste
zip -r my-app-1.0.0.zip my-app.lua my-app/ assets/ -x "*/spec/*" "*/turn.lua" "*.rockspec"

# Verificar conteúdo
unzip -l my-app-1.0.0.zip

Notas Importantes​

NÃO inclua no seu ZIP:

  • Arquivos de teste (diretório spec/)
  • Mock da API Turn (turn.lua)
  • Arquivos de desenvolvimento (*.rockspec, .git/, etc.)
  • Arquivos de documentação (README.md, a menos que em assets/)

INCLUA:

  • Arquivo principal do app (deve corresponder ao nome do app)
  • Arquivo assets/manifest.json (OBRIGATÓRIO)
  • Todos os módulos Lua necessários
  • Pasta de ativos com manifest.json e quaisquer templates/imagens
  • Quaisquer arquivos de configuração que seu app precise

Processo de Upload​

  1. Vá para a plataforma Turn.io
  2. Navegue até Configurações → Apps
  3. Clique em "Carregar Novo App"
  4. Selecione seu arquivo ZIP
  5. A plataforma validará:
    • Presença de assets/manifest.json
    • Estrutura JSON válida no manifest
    • Campos obrigatórios (name, version, description)
    • Formato de versionamento semântico
  6. Após validação bem-sucedida, uma definição de app será criada

Fornecendo Documentação do App na UI​

Para garantir uma ótima experiência do usuário, você pode fornecer documentação que aparecerá diretamente na UI da Turn.io. Lide com o evento get_app_info_markdown e retorne uma string Markdown.

Este é o lugar perfeito para explicar o que seu app faz, listar suas funcionalidades e fornecer instruções de configuração ou exemplos de endpoint de API.

elseif event == "get_app_info_markdown" then
  return [[
# Meu App Incrível

Este app se integra com o serviço externo `XYZ`.

## Configuração

Para usar este app, forneça sua `XYZ_API_KEY` na configuração abaixo.

## Endpoint de Webhook

Envie requisições `POST` do seu serviço para a seguinte URL:
`/apps/]] .. app.uuid .. [[/webhook`
]]
end