southgames_flutter changelog

0.7.3 #

Auto re-identify on app boot — the SDK now persists the identify payload (externalId, email, firstName, lastName, phone) to SharedPreferences after every successful identify() call. On every subsequent init(), _syncClient re-sends that payload to /api/v1/clients/register so the server keeps the client identified even when the integrator app has a persistent session and doesn't re-call identify() on each launch. Fixes the case where users who logged in once stayed anonymous in SouthGames because their session outlived the original identify trigger. Idempotent — the server merges into the same client doc.
logout() clears the persisted identify payload alongside the existing clientId reset.

0.7.2 #

createPromoCode(...) method — New SDK method to create a single promo code for an end user on a campaign. Uses POST /api/v1/codes; params (discount, expiry, prefix, length, maxDiscountAmount) come from the campaign's defaultCodeConfig, enforced server-side. Returns a CreateCodeResult with code, discountType, discountValue, maxDiscountAmount, maxUses, expiresAt, remainingGenerations, limitPeriod, and idempotent fields.
Automatic idempotency — Each call auto-generates a UUID v4 Idempotency-Key header so HTTP-layer retries never produce duplicates. Override by passing idempotencyKey.
Webhook — Server dispatches code.created event on successful generation (not on idempotent replays).

0.7.1 #

Rankings endpoint — New GET /api/v1/rankings support for leaderboard queries by campaign, game type, or organization scope, with all-time, weekly, and monthly periods.

0.7.0 #

Fix API paths — All SDK endpoints now use /api/v1/ (previously /api/sdk/). Resolves 404 errors on all API calls.

0.6.9 #

Campaign imageUrl — Campaign model now exposes imageUrl (nullable). Gaming campaigns return the marketplace game icon; traditional campaigns return their optional campaign image.

0.6.8 #

Unit tests — Added 163 unit tests covering all model fromJson() deserialization (Attribution, Campaign, ClientInfo, CtaButton, GameResult, InAppNotification, Points, PromoCodeResult, TrackEventResult), exceptions, HTTP client (headers, errors, timeouts), SDK config (URL construction, defaults), and notification manager (trigger evaluation, frequency capping, impression tracking).

0.6.7 #

Push & in-app event tracking with clientId — trackInAppEvent and push event tracking now include clientId in the request body, enabling per-user engagement analytics on the server.

0.6.6 #

first_open event — Tracks first_open custom event on first device registration, with automatic retry on next launch if the initial attempt fails.
Offline event queue — Failed trackEvent calls (network errors, 5xx) are persisted and retried on next app start. Events expire after 24 hours. Max queue size: 50.
HTTP timeouts — All API requests now timeout after 30 seconds instead of hanging indefinitely.
Concurrent push dismiss flush — Pending push dismiss events are now sent concurrently instead of sequentially on app start.
Cleanup — Removed redundant debug logging loop in notification fetching, deduplicated OS detection helper.

0.6.5 #

Game view height cap — The game WebView container now uses a maximum of 70% of the screen height, keeping movement buttons and surrounding UI visible.

0.6.4 #

Responsive font sizes — Text sizes in in-app notification blocks now scale proportionally to the device screen width (reference: 375pt), clamped between 0.85x–1.3x to avoid extremes on very small or very large screens.
Full-width buttons — Single buttons in block-based notifications now stretch to fill the available width.
Button text scaling — Button labels use FittedBox to stay on a single line and scale down proportionally when space is limited, ensuring consistent appearance between single and grouped buttons.

0.6.3 #

Singleton pattern — SouthGamesSDK is now a true singleton. Call SouthGamesSDK.init() once, then access the instance from anywhere via SouthGamesSDK.instance. This fixes issues where methods like trackEvent() threw SouthGamesNotInitializedException despite init() having been called.
Instance methods — identify(), trackEvent(), getCampaigns(), play(), redeem(), heartbeat(), registerClient(), getInAppNotifications(), trackInAppEvent(), getPointsBalance(), getPointsHistory(), spendPoints(), earnPoints(), requestPushPermission(), logout(), disableAutoOverlay() are now instance methods accessed via SouthGamesSDK.instance.
Static methods — init(), handleBackgroundMessage(), dispose(), and isInitialized remain static.

0.6.2 #

Fix — Fixed State class name mismatch in NotificationOverlayWidget that caused compilation errors.

0.6.1 #

Fix — Made NotificationOverlayWidget public so auto-overlay can reference it correctly.

0.6.0 #

Auto in-app notifications — In-app notifications now render automatically without requiring SouthGamesNotificationOverlay widget. Just call SouthGamesSDK.init() and notifications appear on top of all routes.
Optional callbacks in init() — onCtaTap and onNotificationShown can now be passed directly to init() instead of requiring the widget.
Static callback setters — SouthGamesSDK.onCtaTap and SouthGamesSDK.onNotificationShown setters for apps that configure callbacks after init.
Backward compatible — SouthGamesNotificationOverlay widget still works. When used, it automatically disables the auto-overlay to prevent duplicates.

0.5.20 #

Global notification overlay — SouthGamesNotificationOverlay now uses a global OverlayEntry so notifications always render on top of all routes and dialogs, even when placed inside a specific view instead of MaterialApp.builder.
HTTP debug logging — logs status code and response body (first 200 chars) when server returns non-JSON responses, making it easier to diagnose API issues.

0.5.19 #

Fix duplicate client creation — SDK now sends persisted clientId on every /register call so the server finds the existing client instead of creating a new one.
Sync on every app start — init() now calls the server on each launch to update deviceToken, location, and metadata for existing clients.
externalId is now optional in identify() and registerClient() — clients can be registered/updated with just deviceToken or clientId.
Server: clientId lookup — /api/sdk/clients/register now accepts clientId as a lookup field, with fallback chain: clientId → externalId → email → deviceToken.

0.5.18 #

Fix 301 redirect on API calls — server-side fix (skipTrailingSlashRedirect) eliminates unnecessary 301 redirects on SDK HTTP requests, reducing latency.

0.5.17 #

Server-side in-app notification analytics — the overlay now reports shown, dismissed, and cta_click events to the server via POST /api/sdk/notifications/in-app/events.
New SouthGamesSDK.trackInAppEvent() static method for custom event tracking on in-app notifications.

0.5.16 #

Disable scroll in HTML notification overlay — set overflow: hidden and height: 100% on both html and body to prevent scrolling inside the WebView modal.

0.5.15 #

Fix isHtml detection — notifications with htmlContent present are now treated as HTML even if contentType field is missing from Firestore (backward compatibility for notifications created before the contentType field existed).

0.5.14 #

Debug logging for HTML notifications — logs raw server response fields (contentType, htmlContent length, modalSize) and overlay state (isHtml, parsed values) to help diagnose rendering issues.

0.5.13 #

Fix HTML notification WebView — replaced Uri.dataFromString (fails on Android with large content) with loadHtmlString for reliable HTML rendering.
Auto-detect full HTML documents — if htmlContent already contains <!DOCTYPE> or <html>, it's loaded as-is without wrapping in another HTML shell.
WebView controller lifecycle — controller is now stored as state and properly cleaned up on dismiss, preventing stale WebView instances.
WebView error logging — added NavigationDelegate with onPageFinished and onWebResourceError for debugging.

0.5.12 #

Fix HTML notification rendering — HTML in-app notifications now display correctly with proper width/height constraints using screen-relative sizing (40%/65%/85%/full).
Fix modalSize mapping — handles both portal values (small, medium, large) and shorthand (sm, md, lg).
Fix Expanded in non-flex parent — replaced with Positioned.fill inside Stack for the WebView widget.

0.5.11 #

HTML in-app notifications — notifications with contentType: "html" now render in a WebView instead of native text widgets. Supports custom HTML/CSS content with full viewport control.
JS bridge for HTML notifications — HTML content can call SouthGamesNotif.postMessage('dismiss') to dismiss or SouthGamesNotif.postMessage('cta:action') to trigger CTA actions.
Modal size support — HTML notifications respect modalSize (sm, md, lg, full) for height control.
Auto-polling for in-app notifications — notifications are fetched automatically after init() and identify(), no manual call needed.
Overlay subscription retry — SouthGamesNotificationOverlay retries subscription in didChangeDependencies if SDK wasn't ready at init.
Fixed double evaluation — polling no longer calls evaluateAndEmit twice per fetch cycle.

0.5.10 #

WebView bridge fix — games now work correctly in Flutter WebView (fake window.parent injection so SDK methods like close(), getConfig(), submitResult() no longer fail with "Not running inside an iframe").
Deduplicated message forwarding — prevent duplicate postMessage handling that caused renderer crashes.
Navigator safety — onClose callback is deferred via addPostFrameCallback to avoid Navigator._debugLocked assertion.
Mounted guard — _respondToGame checks mounted before using the WebView controller, preventing "Bad state" errors on dispose.
Removed client-side submitResult throttle — the bridge no longer blocks repeat submissions (backend handles dedup); fixes "Resultado ya enviado" errors on replay.
trackEvent auto-resolves clientId — uses the internally stored client ID when no explicit clientId or externalId is passed.

0.5.9 #

Fixed synchronization between init() and identify() functions.

0.5.8 #

Anonymous device registration — init() now auto-registers the device as an anonymous client, enabling push notifications from app install without requiring user login.
New SouthGamesSDK.clientId getter — exposes the current client ID (anonymous or identified).
Automatic client merge — when identify() is called after anonymous registration, the anonymous client's tokens are transferred to the identified client and the anonymous record is deleted.
New SouthGamesSDK.logout() method — unregisters the device token from the server, deletes the local FCM token, clears all local state (SharedPreferences), and disposes the SDK.
Client ID persistence via SharedPreferences (sg_client_id, sg_anon_client_id) — survives app restarts.
Token refresh now works for anonymous clients (re-registers via /api/sdk/clients/register-device).

0.5.7 #

Auto-detect and send app version (appVersion) on client registration via package_info_plus.
Send SDK version (sdkVersion) on every registration for version tracking.
Auto-detect geolocation passively on identify() — uses existing permissions only, never requests.
Push notification click and dismiss tracking — clicks tracked on tap, dismisses inferred via SharedPreferences and flushed on next app launch.
New dependency: package_info_plus (>=4.0.0), geolocator (>=6.0.0).

0.5.6 #

New Points System — spendable currency alongside XP progression.
getPointsBalance() — get the current points balance for a user.
getPointsHistory() — get the points ledger (earn/spend history).
spendPoints() — spend points from a user's balance.
earnPoints() — manually trigger a points earn action.
New models: PointsBalance, PointsLedgerEntry, SpendPointsResponse, EarnPointsResponse.
Game play and code redemption now automatically award points when configured.
Webhook dispatch on all major events (game.played, game.won, code.redeemed, client.registered, client.level_up, points.earned, points.spent).

0.5.5 #

Auto-detect device locale (e.g. es-CL) and send it on client registration.
Fix: add debug logging for device token resolution — prints warnings when tokenProvider is missing, returns null, or throws.
RegisterResponse now includes deviceTokenSent field so devs can verify if the token was included.
Token refresh re-registration now logs success/failure instead of silently ignoring errors.
Guard against empty string tokens being sent to the backend.

0.5.4 #

Update README with complete documentation for identify(), tokenProvider, onTokenRefresh, SouthGamesGameView, and manual push registration.
Fix class name references from SouthGames to SouthGamesSDK in all docs and examples.

0.5.3 #

New identify() method: registers the user and automatically sends the device token on every app start.
init() now accepts optional tokenProvider and onTokenRefresh parameters for automatic token management.
Automatic re-registration when the device token is refreshed (via onTokenRefresh stream).

0.5.2 #

Rename SouthGames class to SouthGamesSDK.
Add firstName, lastName, phone, latitude, longitude parameters to registerClient.
Add embedUrl and isMarketplaceGame to Campaign model.
New SouthGamesGameView widget for running marketplace games in a WebView with full postMessage bridge support.
New dependency: webview_flutter: ^4.10.0.

0.5.1 #

Fix default base URL to https://southgames.ai.

0.5.0 #

Breaking: Remove firebase_messaging as a required dependency — Firebase is no longer needed.
registerClient now accepts an optional deviceToken parameter. Pass your own token from any push provider (FCM, APNs, OneSignal, etc.).
Removed enablePush and vapidKey parameters from registerClient.
SouthGamesPush is now a lightweight base class with registerDeviceToken() for manual token registration.
For FCM integration, use the separate southgames_flutter_fcm package (coming soon) or call SouthGames.push.registerDeviceToken() with your own FCM token.

0.4.4 #

Upgrade firebase_messaging to ^16.0.0 for compatibility with firebase_core ^4.0.0.

0.4.3 #

Restore firebase_messaging to ^15.0.0 for compatibility with firebase_core ^4.0.0.

0.4.2 #

Downgrade firebase_messaging dependency from ^14.0.0 to ^13.0.0 for broader compatibility.

0.4.1 #

Downgrade firebase_messaging dependency from ^15.0.0 to ^14.0.0 for broader compatibility.

0.4.0 #

Breaking: registerClient now requires externalId (your platform's user ID) instead of email as primary identifier.
Device token is now obtained internally via FCM — no need to call initPush separately.
Server creates and returns clientId — the developer only provides externalId.
New enablePush parameter (default true) to opt out of push registration.
New vapidKey parameter for Flutter web push token support.
Automatic token refresh listener re-registers with externalId on FCM token change.
Removed SouthGames.initPush() — push is now handled inside registerClient.
Improved OS detection using dart:io Platform with proper web fallback.

0.3.0 #

baseUrl is now optional in SouthGames.init() — defaults to https://portal.southgames.ai.
orgId now accepts the organization slug (e.g. mi-empresa) in addition to the UUID.

0.2.0 #

Add push notification support via Firebase Cloud Messaging.
New SouthGamesPush class (lib/src/push.dart).
SouthGames.initPush(clientId:, vapidKey:) — request permission, obtain FCM token, and register it automatically.
SouthGames.push.onMessage — stream of foreground notifications.
SouthGames.push.onMessageOpenedApp — stream of notification taps from background/terminated state.
SouthGames.push.getInitialMessage() — check if app was launched from a notification tap.
Automatic token re-registration on onTokenRefresh.
New dependency: firebase_messaging: ^15.0.0.

0.1.0 #

Initial release.
Client registration and heartbeat.
List active campaigns (spin wheel, scratch card, trivia, slot machine).
Play games and receive promo codes on win.
Redeem promo codes.
Fetch segment-targeted in-app notifications.

southgames_flutter 0.7.3 southgames_flutter: ^0.7.3 copied to clipboard

Metadata