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.

pub package License: MIT

📦 Instalação

Adicione progma_flutter no seu pubspec.yaml:

dependencies:
  progma_flutter: ^0.5.6

🚀 1. Inicialização Rápida

Inicialize o SDK no main() do seu aplicativo. Agora com suporte a auto config (Zero-config), que detecta automaticamente o package name do app:

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

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

  // Inicialização Zero-config: detecta app label e package name via plataforma
  await Progma.instance.autoConfigure();

  // 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());
}

Nota: Caso precise especificar a chave manualmente, você ainda pode usar Progma.instance.configure(ProgmaOptions(sdkKey: '...')).

🏛️ 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(),
)

🆔 4. 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,
)

💳 5. 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},
);

📊 6. 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',
);

💎 7. Placements & Paywalls (Superwall-style)

Controle de paywalls orientados por servidor (SDUI) com interceptação de features:

// Exibe paywall se o usuário não tiver acesso, e executa o callback após o sucesso
await Progma.instance.registerPlacement(
  context,
  'premium_feature_placement',
  customVariables: {'user_name': 'Alex', 'trial_days': '7'}, // Injeta no SDUI {{ custom.user_name }}
  handler: ProgmaPlacementHandler(
    onPresent: (paywall) => print('Paywall exibido'),
    onDismiss: () => print('Paywall fechado'),
  ),
  feature: () {
    // Código executado apenas se o usuário tiver acesso ou comprar
    Navigator.push(context, MaterialPageRoute(builder: (_) => const PremiumScreen()));
  },
);

🛠️ 8. Central do Assinante (Customer Center)

Widget out-of-the-box para gerenciamento de assinaturas (estilo RevenueCat CustomerCenterView):

// Renderiza o painel de assinaturas, status ativo/inativo e botão de restore
ProgmaCustomerCenter(
  embedded: false, // true para embutir dentro de outra tela
  onManageSubscription: () => print('Usuário solicitou cancelamento/gerenciamento'),
)

📢 9. AdMob & Monetização de Ads

// Rastreie impressões de anúncios com valor financeiro
await Progma.instance.trackAdImpression(
  ProgmaAdFormat.interstitial,
  'ca-app-pub-3940256099942544/1033173712',
  valueMicros: 15000,
  currency: 'USD',
);

// Rastreie recompensas concedidas
await Progma.instance.trackAdReward('rewarded_unit_id', 'coins', 100);

📄 Licença

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

Libraries

progma_flutter