n8n-nodes-growthbook

Plugin para n8n: Integração com GrowthBook para feature flags e experimentos A/B

🎯 Sobre

Este plugin permite integrar o n8n com o GrowthBook, uma plataforma open-source de feature flags e experimentos A/B. Com ele, você pode:

• ✅ Avaliar feature flags em tempo real com detecção automática de tipo
• 🎯 Implementar lógica condicional baseada em features
• 👥 Usar targeting por atributos de usuário
• 🔧 Integrar com GrowthBook Cloud ou self-hosted
• 🎨 Interface visual com ícone oficial do GrowthBook

🚀 Instalação

Via npm (Recomendado)

npm install n8n-nodes-growthbook

Via desenvolvimento local

1. Clone este repositório
2. Execute npm run build
3. Execute npm link para desenvolvimento local

⚙️ Configuração

Credencial GrowthBook API

Configure a credencial no n8n:

1. Vá em Credentials → Add Credential
2. Selecione GrowthBook API
3. Preencha os campos:

| Campo | Descrição | Exemplo | Obrigatório | |-------|-----------|---------|-------------| | Client Key | Client Key do SDK do GrowthBook | sdk-abc123... | ✅ | | API Host | Endpoint da API do GrowthBook | https://cdn.growthbook.io | ✅ | | Ativar Cache | Cache local das features | true | ❌ | | Tempo de Cache | Tempo de vida do cache (segundos) | 300 | ❌ | | Ativar Debug | Logs detalhados para debugging | false | ❌ | | Timeout | Timeout das requisições (ms) | 10000 | ❌ |

📦 Nó Disponível

🔘 GrowthBook

Nó principal que avalia features do GrowthBook com detecção automática de tipo.

🎛️ Parâmetros

| Parâmetro | Tipo | Descrição | |-----------|------|-----------| | Feature | Dropdown | Feature flag a ser avaliada (com detecção automática de tipo) | | Attributes | Lista chave-valor | Atributos para targeting do usuário |

🔄 Saídas Dinâmicas

O nó detecta automaticamente o tipo da feature:

• 🔘 Features Boolean: 2 saídas

  • True: Quando feature = true
  • False: Quando feature = false

• 📦 Features Value: 1 saída

  • True / Value: Sempre retorna o valor (string, number, object)

📊 Dados de Saída

{
  "value": true,
  "isOn": true,
  "featureKey": "nova-interface",
  "attributes": {
    "id": "user-123",
    "plan": "premium"
  },
  "detectedType": "boolean"
}

🎯 Exemplos de Uso

Exemplo 1: Feature Flag Boolean

Cenário: Mostrar nova interface apenas para usuários premium.

[Trigger] → [GrowthBook] → [True: Nova Interface]
                        → [False: Interface Antiga]

Configuração:

• Feature: 🔘 nova-interface (Boolean)
• Attributes:
  • id: user-123
  • plan: premium

Exemplo 2: Feature com Valor

Cenário: Personalizar cor do tema baseado no segmento.

[Trigger] → [GrowthBook] → [True/Value: Usar Cor]

Configuração:

• Feature: 📦 theme-color (Value)
• Attributes:
  • id: user-456
  • segment: vip

Saída:

{
  "value": "#FF6B35",
  "isOn": true,
  "featureKey": "theme-color",
  "detectedType": "value"
}

Exemplo 3: A/B Testing

Cenário: Testar diferentes call-to-actions.

[Webhook] → [GrowthBook] → [True: CTA Variação A]
                        → [False: CTA Padrão]

Configuração:

• Feature: 🔘 cta-experiment (Boolean)
• Attributes:
  • id: {{$json.userId}}
  • country: BR
  • device: mobile

🔧 Funcionalidades Avançadas

✨ Detecção Automática de Tipo

O nó analisa automaticamente cada feature e detecta seu tipo:

• Boolean: Baseado no defaultValue ou rules
• Value: Para strings, numbers, objects
• Ícones visuais: 🔘 para boolean, 📦 para value

🔄 Verificação Não Estrita

Para máxima compatibilidade, o nó cria variações dos atributos:

// Atributo original
{ "id": "123" }

// Variações criadas automaticamente
{
  "id": "123",
  "id_str": "123",
  "id_num": 123
}

🐛 Logs de Debug

Ative debug na credencial para logs detalhados:

[GrowthBook] ========== INÍCIO DA AVALIAÇÃO ==========
[GrowthBook] Feature Key: nova-interface
[GrowthBook] Tipo detectado automaticamente: boolean
[GrowthBook] ✅ Boolean TRUE - enviando para saída "True"

🛠️ Desenvolvimento

Scripts Disponíveis

npm run build    # Compila TypeScript + copia ícones
npm run dev      # Compila com watch mode
npm link         # Link para desenvolvimento local

Estrutura do Projeto

n8n-nodes-growthbook/
├── nodes/
│   ├── GrowthBook.node.ts         # Nó principal
│   └── growthbook-icon.png        # Ícone oficial
├── credentials/
│   └── GrowthBookApi.credentials.ts
├── icons/
│   └── growthbook-icon.png        # Ícone fonte
└── dist/                          # Build final
    ├── nodes/
    │   ├── GrowthBook.node.js
    │   └── growthbook-icon.png    # Ícone copiado
    └── credentials/

🔍 Troubleshooting

Erro: "Error fetching options from GrowthBook"

Soluções:

1. Verifique o Client Key

   • Use o Client Key (não Secret Key)
   • Teste: curl https://cdn.growthbook.io/api/features/SEU_CLIENT_KEY

2. Verifique o API Host

   • GrowthBook Cloud: https://cdn.growthbook.io
   • Self-hosted: sua URL sem barra final

3. Verifique as features

   • Certifique-se que há features criadas no GrowthBook

Feature sempre retorna false

Verificações:

1. Targeting: Confirme as regras no GrowthBook
2. Atributos: Verifique nomes e valores dos atributos
3. Feature ativa: Confirme que a feature está habilitada

Ícone não aparece

Se o ícone não carregar, verifique:

• Arquivo dist/nodes/growthbook-icon.png existe
• Execute npm run build para recriar

📚 Documentação

• SDK GrowthBook
• n8n: Criando nodes customizados
• GrowthBook: Feature Flags

📄 Licença

MIT License - veja LICENSE para detalhes.

🤝 Contribuição

Contribuições são bem-vindas! Por favor:

1. Fork o projeto
2. Crie uma branch para sua feature
3. Commit suas mudanças
4. Push para a branch
5. Abra um Pull Request

Desenvolvido com ❤️ para facilitar experimentação e feature flags em automações n8n.