Progma Flutter SDK #

SDK oficial do ecossistema Progma para controle dinâmico de Feature Flags, Kill-Switch, Paywalls Remotos, Google Play Billing 9.1, Atribuição & Analytics, Referral / Cashback e Notificações Push FCM.

📦 Instalação #

Adicione progma_flutter no seu pubspec.yaml:

dependencies:
  progma_flutter: ^0.5.1

🚀 1. Inicialização Rápida #

Inicialize o SDK no main() do seu aplicativo:

import 'package:flutter/material.dart';
import 'package:progma_flutter/progma_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Inicializa o singleton com cache local offline instantâneo (0ms)
  await Progma.instance.configure(const ProgmaOptions(
    sdkKey: 'progma_sdk_live_abcdef123456',
    endpoint: 'https://api.progma.digital',
  ));

  // Opcional: Registre o token FCM para suporte a push notifications e alertas
  // final token = await FirebaseMessaging.instance.getToken();
  // if (token != null) await Progma.instance.registerPushToken(token);

  runApp(const MyApp());
}

🏛️ Arquitetura Dual-Firebase #

O plugin opera de forma integrada com a arquitetura Dual-Firebase:

• Firebase A (No App Flutter): Conecta com o google-services.json do app para registrar eventos no Google Analytics 4 (GA4) e otimizar campanhas do Google Ads (UAC).
• Firebase B (No Backend Progma): O backend da Progma processa os lotes, calcula o score determinístico, emite o evento derivado high_intent_user e sincroniza o perfil do usuário no Firestore em tempo real (apps/{appId}/profiles/{userId}).

🧠 2. Behavioral Conversion Intelligence #

Rastreie eventos comportamentais e intenção comercial diretamente no Flutter:

// 1. Rastrear evento de produto (+15 pts no score)
await Progma.instance.track('feature_used', {
  'feature_name': 'ai_generator',
  'is_core': true,
});

// 2. Rastrear visualização de oferta (+25 pts)
await Progma.instance.track('paywall_viewed', {
  'placement_id': 'premium_modal',
});

// 3. Rastrear início de checkout (+40 pts)
await Progma.instance.track('checkout_started', {
  'product_id': 'sub_annual_pro',
  'value_micros': '149900000',
  'currency': 'BRL',
});

🛡️ 3. Feature Flags, Kill-Switch & Guards #

O SDK avalia regras de acesso localmente em 0ms com cache offline resiliente:

// 1. Verificação Booleana Rápida
if (Progma.instance.isFeatureEnabled('enable_advanced_workouts')) {
  // Exibir funcionalidade avançada
}

// 2. Verificação com Detalhes e Fallbacks
final access = Progma.instance.checkFeatureAccess('enable_ai_nutrition');
if (!access.isAllowed) {
  print('Bloqueado: ${access.reason}');
}

// 3. Guardião de Interface Reativo
ProgmaFeatureGate(
  featureKey: 'enable_ai_nutrition',
  child: const AdvancedNutritionScreen(),
  lockedBuilder: (context, result) => const CustomProPaywallTeaser(),
)

// 4. Guardião de Versão Mínima Obrigatória
ProgmaVersionGuard(
  currentVersion: '1.0.4',
  child: const HomeScreen(),
)

// 5. Guardião de Emergência (Panic Button)
ProgmaKillSwitchGuard(
  child: const HomeScreen(),
)

🆔 3. Identificador de Suporte & Widget de Rodapé #

Facilita o atendimento ao cliente e a liberação manual de acessos:

// Exibe o ID amigável (ex.: "ID de Suporte: USER-8A2F3C1D") com cópia em 1 toque
const ProgmaSupportFooter(
  prefix: 'ID de Suporte:',
  copyOnTap: true,
)

💳 4. Google Play Billing #

// Consulta produtos e base plans disponíveis
final products = await Progma.instance.queryStoreProducts(
  ['premium_monthly'],
  subscriptions: true,
);

// Executa o fluxo de compra
await Progma.instance.purchaseStoreProduct(
  products.first,
  basePlanId: 'monthly',
  offerId: 'trial-7d',
);

// Restaura compras anteriores
await Progma.instance.restorePurchases(
  knownProducts: {for (final item in products) item.id: item},
);

📊 5. Analytics, Atribuição & Consentimento #

// Consentimento LGPD / GDPR
await Progma.instance.setConsent(ProgmaConsent(
  analytics: ProgmaConsentState.granted,
  advertising: ProgmaConsentState.granted,
));

// Identificação de usuário
await Progma.instance.identify('user-123', attributes: {'plan': 'free'});

// Rastreamento de conversões com dados server-side
await Progma.instance.trackConversion(
  'purchase',
  valueMicros: 19900000,
  currency: 'BRL',
  email: 'usuario@email.com',
);

📄 Licença #

Distribuído sob a licença MIT. Consulte LICENSE para mais detalhes.