SDKs

A integração com o sistema de Feature Flags é feita através de SDKs. Atualmente, temos SDKs para Python e React.

Ambientes

O sistema de Feature Flags do INCD possui quatro ambientes:

• dev - Ambiente de desenvolvimento
• staging - Ambiente de staging
• production - Ambiente de produção
• canary - Ambiente de canary

SDKs Disponíveis

SDK Python

O SDK Python fornece uma maneira simples e eficiente de gerenciar feature flags em aplicações Python.

Recursos Principais

• Fácil integração com poucas linhas de código
• Gerenciamento de flags baseado em ambiente
• Avaliação de flags baseada em contexto
• Logging configurável
• Tratamento abrangente de erros

Requisitos

• Python 3.12 ou superior
• Biblioteca requests

Instalação

Para instalar o SDK, você precisará de um deploy token de autenticação. Para isso, acesse o GitLab e gere um token pessoal com escopo read_package_registry (veja como gerar).

Em seguida, execute o comando abaixo para instalar o SDK com pip:

pip install incd_flags \
  --index-url https://<username>:<token>@gitlab.com/api/v4/projects/64294294/packages/pypi/simple

Uso Básico

from incd_flags import init_client, is_enabled

# Inicializar o cliente
init_client(
    api_key="sua-chave-api",
    environment="production",
    default_context={"app_version": "1.0.0"}  # Opcional
)

# Verificar se uma feature flag está ativada
is_enabled = is_enabled(
    flag_slug="minha-feature-flag",
    context={"user_id": "123"},
    raise_on_error=False,  # Opcional: lança exceções em erros de API
    default_value=False  # Opcional: valor padrão se a requisição falhar
)

if is_enabled:
    # Feature está ativada
else:
    # Feature está desativada

Configuração de Logging

from incd_flags import set_logger_level
set_logger_level("DEBUG")  # Opções: DEBUG, INFO, WARNING, ERROR, CRITICAL

Tratamento de Exceções

from incd_flags.exceptions import (
    ClientNotInitializedError,  # Lançada quando is_enabled é chamado antes de init_client
    ContextDumpError,  # Lançada quando o contexto não pode ser serializado
    RequestError  # Lançada quando a requisição à API falha (se raise_on_error=True)
)

try:
    is_enabled = is_enabled(
        "minha-feature-flag",
        {"user_id": "123"},
        raise_on_error=True
    )
except ClientNotInitializedError:
    # Tratar erro de inicialização
except RequestError:
    # Tratar erro de requisição à API
except ContextDumpError:
    # Tratar erro de serialização de contexto

SDK React

O SDK React permite integrar feature flags em aplicações React de forma simples.

Instalação

Para instalar o SDK, você precisará de um deploy token de autenticação. Para isso, acesse o GitLab e gere um token pessoal com escopo read_package_registry (veja como gerar).

Adicione um arquivo .npmrc na pasta raiz de sua aplicação (onde está o package.json) com o seguinte conteúdo:

@incd:registry=https://gitlab.com/api/v4/projects/64294294/packages/npm/
//gitlab.com/api/v4/projects/64294294/packages/npm/:_authToken="${NPM_TOKEN}"

Em seguida, execute o comando abaixo para instalar o SDK com npm:

NPM_TOKEN=<seu-token> npm install @incd/react-flags

Uso Básico

Primeiro, configure o provedor de flags em sua aplicação:

import { FlagsProvider } from '@incd/react-flags';

const config = {
  baseUrl: 'https://flags.incd.com.br',
  apiKey: 'sua-chave-api',
  environment: 'production',
  defaultContext: { app_version: '1.0.0' }, // opcional
  defaultTtl: 300, // opcional - tempo de cache em segundos
};

function App() {
  return (
    <FlagsProvider config={config}>
      <SeuComponente />
    </FlagsProvider>
  );
}

Então, use o hook useFlag em seus componentes:

import { useFlag } from '@incd/react-flags';

function Component() {
  const flag = useFlag('nome-da-flag', { userId: '12345' });

  if (flag.loading) return <div>Carregando...</div>;
  if (flag.error) return <div>Erro: {flag.error.message}</div>;

  return flag.enabled ? <ActiveFeature /> : <InactiveFeature />;
}

Hook useFlag

O hook useFlag aceita três argumentos:

1. flagName: string - Nome da flag a ser verificada

2. context: Record<string, any> - Objeto com dados de contexto para avaliação da flag. Por exemplo:

3. config?: OptionalIsEnabledConfig - Objeto com configurações adicionais para avaliação da flag.

O retorno do hook é um objeto com as seguintes propriedades:

• enabled: boolean | null - Valor da flag (null enquanto o valor está sendo carregado)
• loading: boolean - Indica se o valor da flag está sendo carregado
• error: Error | null - Qualquer erro que ocorreu durante a avaliação da flag. Apenas se throwOnError === true.

Detalhes

// Tipagem:
export interface IsEnabledConfig {
  throwOnError: boolean;
  defaultValue: boolean;
}

export type OptionalIsEnabledConfig = Partial<IsEnabledConfig>;

type UseFlagResult = {
  enabled: boolean | null;
  loading: boolean;
  error: Error | null;
}

function useFlag(flagName: string, context: Record<string, any>, config?: IsEnabledConfig): UseFlagResult


// Exemplo:
const { enabled, loading, error } = useFlag('nome-da-flag', { userId: '12345' }, {
  throwOnError: true,
  defaultValue: true,
})

Considerações Finais

• Cache: Os SDKs implementam cache para otimizar o desempenho e reduzir chamadas à API.
• Tratamento de Erros: Configurações flexíveis para lidar com falhas de comunicação
• Contextos: Suporte a contextos personalizados para avaliação granular de flags
• Ambientes: Suporte a múltiplos ambientes (development, staging, production)