GameLoom Flutter SDK#
A Flutter package for integrating the GameLoom marketplace into your app. Let your users browse gifts, redeem them using earned points, and view their redemption history — all handled by GameLoom.GameLoom manages stock, point deduction, eligibility filtering, delivery tracking, and localization. You initialize the SDK, log in a user, and drop in the MarketApp widget.
Table of Contents#
Requirements#
Installation#
Add the dependency to your pubspec.yaml:
Quick Start#
Then place the marketplace anywhere in your widget tree:
Configuration#
GameLoomConfigs is passed to GameLoomSDK().init().| Parameter | Type | Required | Description |
|---|
sdkKey | String | Yes | Your private SDK key |
local | SupportedLocale | Yes | UI language: SupportedLocale.en or SupportedLocale.ar |
themeMode | ThemeMode | No | ThemeMode.light, ThemeMode.dark, or ThemeMode.system (default) |
SDK Reference#
Initialization#
Fetches company data (logo, brand colors, corner radius) and prepares the SDK. Must be called before login() or displaying MarketApp.User Login#
The SDK uses userKey to fetch and filter gifts. Targeting (gender, age, country, city, segments) controls which private gifts the user sees.Note: if the user does not exist, login will register them with the provided information (name, gender, birthDate, country, city, segments).Callbacks#
Set these static callbacks before calling init():Debugging#
Enable network request/response logging for development:Set this before calling init(). Disable in production.State#
GameLoomSDK is a BLoC cubit. You can listen to its state stream if you need to react to lifecycle changes:| State | Meaning |
|---|
GameLoomUninitializedState | SDK not yet initialized |
GameLoomInitializingState | init() in progress |
GameLoomInitializedState | init() succeeded |
GameLoomInitializedErrorState | init() failed |
GameLoomLoadedState | User logged in — state.user available |
GameLoomLoadingState | A loading operation is running |
GameLoomErrorState | Error after initialization |
Static getters (available after the respective states are reached):
Displaying the Marketplace#
Drop MarketApp anywhere in your widget tree. It is self-contained and manages its own BLoC providers, theming, and navigation.The marketplace renders two tabs:Shop — browseable gift grid with search, category filtering, price range, and sorting
History — the user's redemption history with order and delivery status
Filter & Sort Options#
Users can filter gifts by:| Filter | Options |
|---|
| Category | Fetched from the server |
| Product type | Product or Coupon |
| Points range | Slider between min/max available |
| Limited edition only | Toggle |
| Sort by | Featured, Points (low→high), Points (high→low), Name (A→Z) |
Models#
User#
Product#
Returned from the marketplace browse and detail endpoints.| Field | Type | Description |
|---|
id | String | Gift ID |
name | String | Resolved to the configured language |
imageUrl | String? | Gift image URL |
categoryName | String | Category label |
description | String? | Gift description |
pricePoints | double? | Points cost |
priceSar | double? | SAR cost |
priceDisplay | ProductPriceDisplay | points, sar, or both |
isUnlimited | bool | Whether stock is unlimited |
remainingStock | int? | null when unlimited |
ranking | int? | Display order (lower = first) |
collectCustomerInfo | bool | Whether name + phone are required at redemption |
deliveryRequired | bool | Whether a delivery address is required |
expiresAt | DateTime? | Gift expiry |
createdAt | DateTime | Creation timestamp |
Redemption#
Returned after a successful redemption.| Field | Type | Description |
|---|
redemptionMessage | String? | Message to display to the user |
redemptionValue | String? | Voucher code or delivery confirmation |
ProductHistory#
| Field | Type | Description |
|---|
id | String | Redemption ID |
giftName | String | Name of the redeemed gift |
giftImageUrl | String? | Gift image URL |
pointsSpent | double | Points deducted |
orderStatus | OrderStatus | completed, failed, or cancelled |
deliveryStatus | DeliveryStatus? | pending or completed |
deliveryRequired | bool | Whether delivery info was collected |
createdAt | DateTime | Redemption timestamp |
Theming#
The SDK pulls brand colors and corner radius from your company settings automatically after init(). You can also configure the theme mode via GameLoomConfigs.themeMode.Default light theme colors:Default dark theme colors:If your company has configured custom colors in the GameLoom dashboard, those override the defaults.
Localization#
The SDK ships with full English and Arabic support, including RTL layout for Arabic.Set the locale during initialization:All gift names, images, redemption messages, and error messages are resolved server-side to the configured language. If a translation does not exist, the default value is returned.
Error Handling#
The SDK surfaces errors through the GameLoomSDK.onFailure callback. Set it before calling init():
Dependency Resolution#
The SDK uses the following packages internally. If you encounter version conflicts with your app's dependencies, use dependency_overrides in your pubspec.yaml to resolve them:| Package | Version constraint |
|---|
flutter_bloc | >=9.0.0 <10.0.0 |
dio | >=5.0.0 <6.0.0 |
dio_cache_interceptor | >=4.0.0 <5.0.0 |
dartz | ^0.10.1 |
intl | bundled via flutter_localizations |
Modified at 2026-05-22 12:25:13
