bemall_sdk 1.1.8

Flutter SDK for BeMall Promotion and Loyalty Club services.

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>

Os 3 valores que você precisa

A BeMall entrega estes valores para o seu app:

Valor	O que é
customerId	Identificador do cliente (tenant) na BeMall. Ex.: acme.
campaignHash	Código da promoção / do Loyalty Club (o "hash" da campanha). Diz ao SDK qual campanha abrir.
customerAccessToken	Token do usuário logado no seu app, gerado pelo seu backend. Opcional no Loyalty Club (sem ele abre deslogado).

Navbar (você controla cor, texto e altura)

O SDK abre em tela cheia e, sozinho, não desenha barra superior. Para ter uma, passe um BeMallNavBar (sem código Swift ou Kotlin no app):

await BeMallSdk.instance.initialize(
  config,
  navBar: const BeMallNavBar(
    title: 'Meu Clube',
    color: 0xFF0A3D91,     // fundo (ARGB)
    textColor: 0xFFFFFFFF, // título e seta
    height: 44,
  ),
);

A seta fecha o SDK mantendo a sessão. Para usar um widget seu como navbar, passe BeMallNavBar.widget(entrypoint: minhaFuncaoTopLevel, height: 56): o widget roda numa segunda engine Flutter dentro da faixa do topo e chama BeMallNavBar.close() para fechar o SDK. Os guias passo a passo (copiar e colar) estão em flutter-loyalty-club.md e flutter-promotion.md.

Uso rápido

import 'package:bemall_sdk/bemall_sdk.dart';

Future<void> startPromotion() async {
  try {
    await BeMallSdk.instance.initialize(
      const BeMallSdkConfig.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.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 (obrigatório no Loyalty Club; opcional no Promotion).

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.