southgames_flutter 0.5.18

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 externalId con custom params y device tokens.
• Idioma automático — detecta el locale del dispositivo (ej: es-CL) y lo envía al registrar.
• Identificación automatica — envía y refresca el device token en cada inicio de app.
• Campañas activas — listado de campañas con configuración de juego.
• 4 tipos de juego — spin wheel, scratch card, trivia y slot machine.
• Juegos del marketplace — carga juegos HTML5 en WebView con SouthGamesGameView.
• Códigos promocionales — generación automatica al ganar + canje.
• Sistema de puntos — consultar saldo, historial, gastar y ganar puntos canjeables.
• Notificaciónes in-app — filtradas por segment rules del cliente.
• Push notifications — registro de device tokens con cualquier proveedor (FCM, APNs, etc.).

Instalación

Agrega southgames_flutter a tu pubspec.yaml:

dependencies:
  southgames_flutter: ^0.5.6

Luego ejecuta:

flutter pub get

Inicio rápido

import 'package:southgames_flutter/southgames_flutter.dart';
// Si usas Firebase Cloud Messaging:
// import 'package:firebase_messaging/firebase_messaging.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. Inicializar el SDK
  SouthGamesSDK.init(
    apiKey: 'sg_live_xxxxxxxxxxxxxxxx',
    orgId: 'tu-org-slug',
    // Token automático con FCM (opciónal):
    // tokenProvider: () => FirebaseMessaging.instance.getToken(),
    // onTokenRefresh: FirebaseMessaging.instance.onTokenRefresh,
  );

  runApp(const MyApp());
}

// 2. Identificar al usuario (envía el token automáticamente)
final res = await SouthGamesSDK.identify(
  externalId: 'user_123',
  email: '[e-mail]',
  customParams: {'plan': 'premium'},
);
print('Client ID: ${res.clientId}');

// 3. Obtener campañas activas
final campaigns = await SouthGamesSDK.getCampaigns();

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

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

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

Uso

Inicialización

Llama a SouthGamesSDK.init() antes de usar cualquier otro método. Generalmente en main().

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

Token automático (recomendado)

Para envíar y refrescar el device token automáticamente en cada inicio de app, pasa tokenProvider y onTokenRefresh:

SouthGamesSDK.init(
  apiKey: 'sg_live_xxxxxxxxxxxxxxxx',
  orgId: 'tu-org-slug',
  tokenProvider: () => FirebaseMessaging.instance.getToken(),
  onTokenRefresh: FirebaseMessaging.instance.onTokenRefresh,
);

• tokenProvider: callback async que retorna el token actual del dispositivo.
• onTokenRefresh: stream que emite tokens nuevos cuando se refrescan.

Cuando se usa junto con identify(), el SDK:

1. Obtiene el token via tokenProvider y lo envía al registrar al usuario.
2. Escucha onTokenRefresh y re-registra automáticamente cuando el token cambia.

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

Identificación de usuario

identify() registra o actualiza al usuario y envía el device token automáticamente. El idioma del dispositivo (ej: es-CL) se detecta y envía automáticamente. Llámalo en cada inicio de app una vez que conozcas la identidad del usuario.

final res = await SouthGamesSDK.identify(
  externalId: 'user_123',       // ID del usuario en tu plataforma
  email: '[e-mail]',    // opciónal
  firstName: 'Juan',            // opciónal
  lastName: 'Perez',            // opciónal
  phone: '[phone]',        // opciónal
  latitude: -33.45,             // opciónal
  longitude: -70.66,            // opciónal
  customParams: {'tier': 'gold'}, // opciónal
);

print(res.clientId);        // ID único del cliente en SouthGames
print(res.created);         // true si es nuevo, false si se actualizó
print(res.deviceTokenSent); // true si el device token fue envíado

Debug: El SDK imprime logs con el prefijo [SouthGames] en la consola de debug. Si el token no se está envíando, busca mensajes como "No tokenProvider configured" o "tokenProvider returned null".

Registro manual de cliente

Si necesitas más control, puedes usar registerClient() directamente:

final res = await SouthGamesSDK.registerClient(
  externalId: 'user_123',
  email: '[e-mail]',
  deviceToken: 'fcm_or_apns_token', // opciónal
);

Heartbeat

Actualiza lastSeenAt del cliente. Útil para trackear actividad.

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

Campañas activas

Retorna las campañas con status == "active" dentro de su rango de fechas.

final campaigns = await SouthGamesSDK.getCampaigns();

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

Jugar un juego

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

// Trivia (requiere respuestas)
final triviaPlay = await SouthGamesSDK.play(
  campaignId: 'trivia_campaign_id',
  externalUserId: 'user_123',
  answers: [0, 2, 1, 3], // índice de la opción elegida por pregunta
);

print(play.won);        // true si ganó
print(play.prizeCode);  // código promo si ganó, null si no
print(play.result);     // descripción del resultado
print(play.metadata);   // metadata especifica del juego

Juegos del marketplace (WebView)

Para campañas con juegos del marketplace, usa SouthGamesGameView:

if (campaign.isMarketplaceGame) {
  Navigator.push(context, MaterialPageRoute(
    builder: (_) => SouthGamesGameView(
      campaign: campaign,
      externalUserId: 'user_123',
      onResult: (result) {
        print(result.won ? 'Ganaste!' : 'No ganaste');
        Navigator.pop(context);
      },
      onClose: () => Navigator.pop(context),
      onError: (error) => print('Error: $error'),
    ),
  ));
}

Canjear código promocional

final redeem = await SouthGamesSDK.redeem(
  code: 'SG-AB2C-XY9Z',
  externalUserId: 'user_123', // opciónal
);

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

Notificaciónes in-app

Retorna notificaciónes activas que matchean las segment rules del cliente.

final notifications = await SouthGamesSDK.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}');
  }
}

Puntos

Consulta el saldo, historial, gasta y gana puntos canjeables.

// Consultar saldo
final balance = await SouthGamesSDK.getPointsBalance(
  externalUserId: 'user_123',
);
print('${balance.pointsName}: ${balance.pointsBalance}');
print('Ganados: ${balance.pointsEarned}');
print('Gastados: ${balance.pointsSpent}');

// Historial de puntos
final history = await SouthGamesSDK.getPointsHistory(
  externalUserId: 'user_123',
  limit: 10,
);
for (final entry in history) {
  print('${entry.type}: ${entry.amount} — ${entry.reason}');
}

// Gastar puntos
try {
  final spend = await SouthGamesSDK.spendPoints(
    externalUserId: 'user_123',
    amount: 100,
    reason: 'Canje por descuento',
  );
  print('Gastaste ${spend.pointsSpent} puntos. Saldo: ${spend.newBalance}');
} on SouthGamesException catch (e) {
  if (e.code == 'INSUFFICIENT_BALANCE') {
    print('Saldo insuficiente');
  }
}

// Ganar puntos manualmente
final earn = await SouthGamesSDK.earnPoints(
  externalUserId: 'user_123',
  action: 'custom',
  eventName: 'purchase_completed',
);
print('Ganaste ${earn.pointsAwarded} puntos. Saldo: ${earn.newBalance}');

Nota: Los puntos también se ganan automáticamente al jugar, ganar juegos y canjear códigos, si hay reglas de ganancia configuradas en el dashboard.

Push notifications (manual)

Si no usas tokenProvider/onTokenRefresh, puedes registrar tokens manualmente:

await SouthGamesSDK.push.registerDeviceToken(
  externalId: 'user_123',
  token: 'fcm_or_apns_token',
);

Limpieza

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

SouthGamesSDK.dispose();

Manejo de errores

Todas las llamadas pueden lanzar SouthGamesException:

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

Códigos de error comunes

Código	HTTP	Descripción
MISSING_API_KEY	401	Falta API key
MISSING_ORG_ID	401	Falta org ID
INVALID_API_KEY	401	API key inválida o inactiva
API_KEY_EXPIRED	401	API key expirada
VALIDATION_ERROR	400	Datos de entrada inválidos
NOT_FOUND	404	Recurso no encontrado
CAMPAIGN_INACTIVE	400	Campaña no activa
CODE_NOT_FOUND	404	Código promo no existe
CODE_INACTIVE	400	Código desactivado
CODE_EXPIRED	400	Código expirado
CODE_MAX_USES_REACHED	400	Código sin usos restantes
INSUFFICIENT_BALANCE	400	Saldo de puntos insuficiente
POINTS_NOT_ENABLED	400	Sistema de puntos no habilitado

Modelos

Clase	Descripción
RegisterResponse	Resultado del registro (clientId, created, deviceTokenSent)
Campaign	Campaña activa (id, name, gameType, config, fechas)
PlayResponse	Resultado de jugar (sessionId, won, prizeCode, metadata)
RedeemResult	Resultado de canje (discountType, discountValue, remainingUses)
InAppNotification	Notificación in-app (title, body, type, position, cta, colores)
CtaButton	Botón CTA de notificación (label, action)
PointsBalance	Saldo de puntos (pointsBalance, pointsEarned, pointsSpent, pointsName)
PointsLedgerEntry	Entrada del historial de puntos (type, amount, balance, reason)
SpendPointsResponse	Resultado de gastar puntos (pointsSpent, newBalance)
EarnPointsResponse	Resultado de ganar puntos (pointsAwarded, newBalance, totalEarned)

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.