bemall_sdk

SDK Flutter oficial da BeMall para os serviços Promotion e Loyalty Club, com binários nativos (Android/iOS) já embutidos.

Recursos

  • API única para Promotion e Loyalty Club.
  • Resolução de URL HTTPS no layer nativo.
  • Persistência segura de sessão no dispositivo.
  • Suporte nativo a câmera, galeria, QR/barcode, parking-ticket e upload de comprovante.
  • Eventos de ciclo da WebView via stream (pageLoaded, pageError, closed, unauthenticated).
  • Origem da visita (BeMallUtm), consentimento de marketing (mktOptIn) e navbar nativa (topInset).

Requisitos

  • Flutter >= 3.29.0
  • Dart SDK ^3.7.2
  • Android minSdk 21 (recomendado compileSdk 36 no app host)
  • iOS 14.0+

Instalação

flutter pub add bemall_sdk

No iOS, execute também:

cd ios && pod install

Configuração de permissões

No Android, o SDK já declara as permissões necessárias no AAR.

No iOS, adicione no Info.plist do app host:

<key>NSCameraUsageDescription</key>
<string>A câmera é usada para fotografar comprovantes e ler QR codes.</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>A galeria é usada para selecionar fotos de comprovantes e tickets.</string>

<key>NSFaceIDUsageDescription</key>
<string>O Face ID protege a restauração da sessão BeMall.</string>

Uso rápido

import 'package:bemall_sdk/bemall_sdk.dart';

Future<void> startPromotion() async {
  try {
    await BeMallSdk.instance.initialize(
      const BeMallSdkConfig(
        service: BeMallService.promotion,
        customerId: 'tenant-do-cliente',
        customerAccessToken: 'token-opcional',
        campaignHash: 'hash-opcional',
      ),
    );
  } on BeMallSdkException catch (e) {
    // Trate erros de plataforma/integração.
    print('${e.code}: ${e.message}');
  }
}

Abrir, fechar e sessão

// Abre a tela do SDK com a configuração já inicializada.
await BeMallSdk.instance.open();

// Fecha a tela mantendo a sessão (dispara o evento `closed`).
await BeMallSdk.instance.close();

// Há sessão segura persistida no dispositivo?
final hasSession = await BeMallSdk.instance.hasPersistedSession;

// dispose() libera o SDK; reset() descarta a sessão salva.

initialize sem customerAccessToken sempre abre deslogado: qualquer sessão anterior (cookies, dados do site, configuração salva, biometria) é descartada.

Opções de initialize e open

await BeMallSdk.instance.initialize(
  const BeMallSdkConfig(
    service: BeMallService.promotion,
    customerId: 'tenant-do-cliente',
    campaignHash: 'hash-da-campanha',
  ),
  // Origem da visita. Sem isso o SDK usa o nome do app, `app` e o hash.
  utm: const BeMallUtm(
    source: 'newsletter',
    medium: 'email',
    campaign: 'black-friday',
    // Cada par vira um parâmetro `utm_custom_<chave>`.
    custom: {'loja': '42', 'canal': 'qr'},
  ),
  // Consentimento de marketing já dado no seu app:
  // 'accepted', 'rejected' ou 'ask'. Outros valores são ignorados.
  mktOptIn: 'accepted',
  // Faixa reservada no topo (pt no iOS, dp no Android) para a navbar nativa do app.
  topInset: 56,
);

open() aceita os mesmos utm, mktOptIn e topInset.

Eventos

final subscription = BeMallSdk.instance.events.listen((event) {
  switch (event.type) {
    case BeMallSdkEventType.pageLoaded:
      print('Página carregada');
    case BeMallSdkEventType.pageError:
      print('Erro: ${event.description} (${event.errorCode})');
    case BeMallSdkEventType.closed:
      print('Tela do SDK fechada');
    case BeMallSdkEventType.unauthenticated:
      // Promotion aberto sem usuário autenticado (ex.: sem token).
      // O SDK limpa os dados do site e avisa uma vez; quem fecha é o app.
      BeMallSdk.instance.close();
    case BeMallSdkEventType.unknown:
      print('Evento desconhecido');
  }
});

// Quando não precisar mais observar os eventos:
await subscription.cancel();

Erros

initialize, open, close e demais chamadas lançam BeMallSdkException com code e message. Exemplos de code: authorization_unreachable (a validação do token não obteve resposta HTTP: rede, DNS ou certificado) e invalid_customer_access_token (token recusado).

Parâmetros por serviço

  • service: BeMallService.promotion ou BeMallService.loyaltyClub.
  • customerId: tenant do cliente na BeMall (obrigatório).
  • customerAccessToken: token de autenticação do usuário (opcional).
  • campaignHash: hash de campanha (opcional).

Promotion: o campaignHash é aplicado no path (/promotion/mobile/<hash>/). Loyalty Club: com token a URL é /loyaltyclub/mobile/auth?token=<token>; sem token abre a home da campanha (/loyaltyclub/mobile/<hash>/home).

Exemplo

Veja o app completo, com Promotion e Loyalty Club, em example/lib/main.dart.

Para Loyalty Club, troque apenas service: BeMallService.loyaltyClub; customerId, customerAccessToken e campaignHash seguem os mesmos parâmetros.

Licença

Licença proprietária Be sistemas.

Libraries

bemall_sdk