southgames_flutter 0.3.0

Flutter SDK for SouthGames — integrate gamification and loyalty features (spin wheel, scratch cards, trivia, slot machine, promo codes, in-app notifications) into your Flutter app with a single package.

SouthGames Flutter SDK

Flutter SDK para integrar gamificación y loyalty de SouthGames en tu app.

Funcionalidades

• Registro de clientes — upsert por email con custom params y device tokens.
• Campanas activas — listado de campanas con configuración de juego.
• 4 tipos de juego — spin wheel, scratch card, trivia y slot machine.
• Codigos promocionales — generación automática al ganar + canje.
• Notificaciones in-app — filtradas por segment rules del cliente.

Instalación

Agrega southgames_flutter a tu pubspec.yaml:

dependencies:
  southgames_flutter: ^0.1.0

Luego ejecuta:

flutter pub get

Inicio rápido

import 'package:southgames_flutter/southgames_flutter.dart';

// 1. Inicializar (una sola vez, por ejemplo en main())
SouthGames.init(
  apiKey: 'sg_live_xxxxxxxxxxxxxxxx',
  orgId: 'tu-org-slug',
);

// 2. Registrar al usuario
final client = await SouthGames.registerClient(
  email: '[e-mail]',
  os: 'android',
  customParams: {'plan': 'premium'},
  deviceToken: 'fcm_token_xxx',
);
print('Client ID: ${client.clientId}');

// 3. Obtener campanas activas
final campaigns = await SouthGames.getCampaigns();

// 4. Jugar
final play = await SouthGames.play(
  campaignId: campaigns.first.id,
  externalUserId: 'user_123',
);

if (play.won && play.prizeCode != null) {
  print('Ganaste! Codigo: ${play.prizeCode}');
}

// 5. Canjear un codigo
final redeem = await SouthGames.redeem(code: play.prizeCode!);
print('Descuento: ${redeem.discountValue}%');

Uso

Inicialización

Llama a SouthGames.init() antes de usar cualquier otro metodo. Generalmente en main() o en el initState() de tu widget raíz.

SouthGames.init(
  apiKey: 'sg_live_xxxxxxxxxxxxxxxx',
  orgId: 'tu-org-slug',
);

Nota: Si usas el SDK sin llamar a init(), se lanza SouthGamesNotInitializedException.

Registro de cliente

Registra o actualiza un cliente. Si el email ya existe, se actualiza os, lastSeenAt, se hace merge de customParams, y se agrega el deviceToken sin duplicar.

final res = await SouthGames.registerClient(
  email: '[e-mail]',
  os: 'ios',                                // 'android' | 'ios' | 'web'
  customParams: {'tier': 'gold'},            // opcional
  deviceToken: 'apns_or_fcm_token',          // opcional
);

print(res.clientId); // ID único del cliente
print(res.created);  // true si es nuevo, false si se actualizó

Heartbeat

Actualiza lastSeenAt del cliente. Util para trackear actividad.

await SouthGames.heartbeat(clientId: 'client_id');

Campanas activas

Retorna las campanas con status == "active" dentro de su rango de fechas. Las respuestas correctas de trivia se omiten por seguridad.

final campaigns = await SouthGames.getCampaigns();

for (final c in campaigns) {
  print('${c.name} (${c.gameType})');
}

Jugar un juego

// Spin wheel / scratch card / slot machine
final play = await SouthGames.play(
  campaignId: 'campaign_id',
  externalUserId: 'user_456',
);

// Trivia (requiere respuestas)
final triviaPlay = await SouthGames.play(
  campaignId: 'trivia_campaign_id',
  externalUserId: 'user_456',
  answers: [0, 2, 1, 3], // indice de la opcion elegida por pregunta
);

print(play.won);        // true si gano
print(play.prizeCode);  // codigo promo si gano, null si no
print(play.result);     // descripcion del resultado
print(play.metadata);   // metadata especifica del juego

Canjear codigo promocional

final redeem = await SouthGames.redeem(
  code: 'SG-AB2C-XY9Z',
  externalUserId: 'user_456', // opcional
);

print(redeem.success);        // true
print(redeem.discountType);   // 'percentage' | 'fixed'
print(redeem.discountValue);  // ej: 20
print(redeem.remainingUses);  // usos restantes

Notificaciones in-app

Retorna notificaciones activas que matchean las segment rules del cliente.

final notifications = await SouthGames.getInAppNotifications(
  clientId: 'client_id',
);

for (final n in notifications) {
  print('${n.title} — ${n.body}');
  if (n.cta != null) {
    print('CTA: ${n.cta!.label} -> ${n.cta!.action}');
  }
}

Limpieza

Libera los recursos del HTTP client cuando ya no necesites el SDK.

SouthGames.dispose();

Manejo de errores

Todas las llamadas pueden lanzar SouthGamesException:

try {
  await SouthGames.redeem(code: 'INVALID');
} on SouthGamesException catch (e) {
  print(e.message);    // "Codigo no encontrado"
  print(e.code);       // "CODE_NOT_FOUND"
  print(e.statusCode); // 404
}

Codigos de error comunes

Codigo	HTTP	Descripción
MISSING_API_KEY	401	Falta API key
MISSING_ORG_ID	401	Falta org ID
INVALID_API_KEY	401	API key invalida o inactiva
API_KEY_EXPIRED	401	API key expirada
VALIDATION_ERROR	400	Datos de entrada invalidos
NOT_FOUND	404	Recurso no encontrado
CAMPAIGN_INACTIVE	400	Campana no activa
CODE_NOT_FOUND	404	Codigo promo no existe
CODE_INACTIVE	400	Codigo desactivado
CODE_EXPIRED	400	Codigo expirado
CODE_MAX_USES_REACHED	400	Codigo sin usos restantes

Modelos

Clase	Descripción
RegisterResponse	Resultado del registro (clientId, created)
Campaign	Campana activa (id, name, gameType, config, fechas)
PlayResponse	Resultado de jugar (sessionId, won, prizeCode, metadata)
RedeemResult	Resultado de canje (discountType, discountValue, remainingUses)
InAppNotification	Notificacion in-app (title, body, type, position, cta, colores)
CtaButton	Boton CTA de notificacion (label, action)

Requisitos

• Dart SDK >=3.0.0 <4.0.0
• Flutter >=3.10.0
• Una cuenta en SouthGames con API key activa

Licencia

MIT — ver LICENSE.