Flutter SDK Analytics

The SDK provides APIs for tracking application-level analytics events.

Custom events

await MagifyClient.instance.trackCustomEvent(
  'level_complete',
  parameters: {
    'level_number': 12,
    'duration_seconds': 87.5,
    'used_hint': true,
  },
);

trackCustomEvent(String name, {Map<String, Object>? parameters}) sends an arbitrary named event. Parameter values may be String, int, double or bool.

The SDK logs validation warnings about the event name and parameter keys — this is advisory only and never blocks the send:

• snake_case
• no leading digit
• no trailing underscore
• at most 90 characters
• not a reserved name

These warnings are only visible in the device logs, not as a Dart callback.

Transactions

trackTransaction(MagifyTransaction transaction) reports a soft-currency movement. No campaign is required — this call always works the same way regardless of what triggered it.

MagifyTransaction has three factories, each carrying a non-empty list of MagifyBonus:

await MagifyClient.instance.trackTransaction(
  MagifyTransaction.receive(
    source: 'level_complete',
    bonuses: [
      MagifyBonus(name: 'coins', quantity: 100, finalBalance: 350, group: 'currency'),
    ],
  ),
);

MagifyBonus({required name, required quantity, required finalBalance, group}) describes one line of the transaction — quantity must not be negative, direction comes from which factory you used, not from the sign. MagifyProductInfo({required productId, price, currency}) describes the product that paid for a receive.

Purchases

trackExternalPurchase and trackExternalTrustedPurchase report purchases, and are covered in full detail in Purchases — including how server-side validation and subscription/in-app activation work. In short:

await MagifyClient.instance.trackExternalPurchase(
  MagifyPurchase.subscription(
    productId: 'week_premium_subscription',
    price: '4.99',
    currency: 'USD',
    transactionId: '2000000123456789',
    isTrial: false,
  ),
);

Game state context

Attach game-state metadata to all subsequent analytics events. Call these methods whenever the values change.

// Current game mode (e.g. "pvp", "story")
await MagifyClient.instance.setGameMode('story');

// Current level the user is on
await MagifyClient.instance.setGameLevel(12);

// Highest level the user has reached
await MagifyClient.instance.setGameMaxLevel(15);

Pass null to any setter to clear the value:

await MagifyClient.instance.setGameMode(null);

User email

Associate a user email address with analytics events for mailing-status mapping:

await MagifyClient.instance.setUserEmail('user@example.com');

Next step

Continue to Purchases to see how purchase and transaction tracking fit together, or to Advertisement for ad impression reporting.