Markopolo Documentation

Appearance

WARNING

Default events (such as those automatically tracked on the web) are not supported in the mobile SDK.

Event names (PascalCase) ​

All MarktagEvent names must be PascalCase (for example AddToCart, ViewItem, PageView). Names in snake_case (add_to_cart) or camelCase (addToCart) throw an ArgumentError and are not sent.

Use a PascalCase string for event, or the matching MarktagEvents constant (the constant name is camelCase in Dart, but the value sent is always PascalCase):

event value (PascalCase)
"AddPaymentInfo"
"AddToCart"
"AddToWishlist"
"BeginCheckout"
"Fcm"
"InitiateCheckout"
"Login"
"PageView"
"Purchase"
"Refund"
"RemoveFromCart"
"Search"
"Share"
"Signup"
"ViewCart"
"ViewContent"
"ViewItem"

Equivalent: event: MarktagEvents.addToCart sends "AddToCart".

Custom events must also be PascalCase, for example "MyCustomEvent".

Metadata keys (snake_case) ​

Only the event field uses PascalCase. Keys inside metadata use snake_case (same as the web SDK), for example payment_type, shipping_cost, transaction_id, search_term. Do not use camelCase metadata keys such as paymentType or shippingCost.

Prerequisites ​

Schema definition for MarktagEventItem:

KeyTypeRequiredDescription
idString✅Unique id of product
nameString❌Product Name eg. "Shirt"
categoryString❌Product Category eg. "Apparel" or "Apparel, Men's Clothing"
variantsList❌Array of variant objects. The array itself is optional, but when provided, each object requires: attributes (Map of key-value string pairs, e.g. { "size": "M", "color": "red" }), price (object with original (double, required), discounted (double, optional), currency (String, required)), and isAvailable (bool).
quantityint❌Quantity of this product added to cart or purchased eg. 5
pricedouble❌Original price of the product before any discount eg. 7.59
descriptionString❌Description of the Product
couponString❌Any coupon used through checkout
discountdouble❌⚠️ Deprecated soon. Use discounted instead. Any monetary discount added to the product
discounteddouble❌The discounted price of the product (final price after discount)
image_urlString❌URL of the product image
urlString❌URL of the product page. If not provided, the current page URL will be used. Recommended if your URL contains tracking parameters

Log Custom Event ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "CustomEvent", // PascalCase required
    metadata: {
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
  ),
);

Log View Item ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "ViewItem",
    metadata: {
      "currency": "USD",
      "value": 119.99,
      "type": "product",
    },
    items: [
      MarktagEventItem(
        id: "edea4360-5752-4b74-a8bf-0162fc809f06",
        name: "Keychron K2 Pro",
        description: "Mechanical Keyboard",
        variants: [
          {
            "attributes": { "type": "VA", "color": "Black" },
            "price": { "original": 119.99, "discounted": 109.99, "currency": "USD" },
            "isAvailable": true
          }
        ],
        coupon: "10_OFF",
        discount: 9.99,
        discounted: 109.99,
        price: 119.99,
        quantity: 1,
        category: "keyboard",
      ),
    ],
  ),
);

Log Page View (Manual) ​

Logs a PageView event (event: "PageView").

dart
Marktag.instance.logPageView("/dashboard");

Log Page Views (Automatic) ​

Add the MarktagNavigatorObserver to your navigatorObservers in MaterialApp

dart
MaterialApp(
  // Your app configuration
  navigatorObservers: [
    // Add this observer to automatically log page views
    MarktagNavigatorObserver(
      marktag: Marktag.instance,
    ),
  ],
);

Log View Content ​

Log view content takes in any parameters you provide.

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "ViewContent",
    metadata: {
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
  ),
);

Log View Cart ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "ViewCart",
    metadata: {
      "currency": "USD",
      "value": 119.99,
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
    items: [
      MarktagEventItem(
        id: "edea4360-5752-4b74-a8bf-0162fc809f06",
        name: "Keychron K2 Pro",
        description: "Mechanical Keyboard",
        variants: [
          {
            "attributes": { "type": "VA", "color": "Black" },
            "price": { "original": 119.99, "discounted": 109.99, "currency": "USD" },
            "isAvailable": true
          }
        ],
        coupon: "10_OFF",
        discount: 9.99,
        discounted: 109.99,
        price: 119.99,
        quantity: 1,
        category: "keyboard",
      ),
    ],
  ),
);

Log Add Payment Info ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "AddPaymentInfo",
    metadata: {
      "payment_type": "credit_card",
      "currency": "USD",
      "value": 120,
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
    items: [
      // Optional MarktagEventItem list
    ],
  ),
);

Log Add to Wishlist ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "AddToWishlist",
    metadata: {
      "currency": "USD",
      "value": 120,
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
    items: [
      // Optional MarktagEventItem list
    ],
  ),
);

Log Begin Checkout ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "BeginCheckout",
    metadata: {
      "currency": "USD",
      "value": 120,
      "shipping_cost": 10,
      "tax": 5,
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
    items: [
      // Optional MarktagEventItem list
    ],
  ),
);

Log Add To Cart ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "AddToCart",
    metadata: {
      "currency": "USD",
      "value": 120,
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
    items: [
      // Optional MarktagEventItem list
    ],
  ),
);

Log Initiate Checkout ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "InitiateCheckout",
    metadata: {
      "currency": "USD",
      "value": 120,
      "shipping_cost": 10,
      "tax": 5,
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
    items: [
      // Optional MarktagEventItem list
    ],
  ),
);

Log Login ​

Prefer logLogin, which sends a Login event and updates the user profile:

dart
Marktag.instance.logLogin(
  email: "user@email.com",
  phone: "xxxxxxxxxxx",
  name: "Test User",
);

Or use logEvent directly:

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "Login",
    email: "user@email.com",
    phone: "xxxxxxxxxxx",
    metadata: {
      "method": "email",
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
  ),
);

Log Signup ​

Prefer logSignup, which sends a Signup event and updates the user profile:

dart
Marktag.instance.logSignup(
  email: "user@email.com",
  phone: "xxxxxxxxxxx",
  name: "Test User",
);

Or use logEvent directly:

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "Signup",
    email: "user@email.com",
    phone: "xxxxxxxxxxx",
    metadata: {
      "method": "email",
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
  ),
);

Log Purchase ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "Purchase",
    metadata: {
      "currency": "USD",
      "value": 120,
      "transaction_id": "1234567890",
      "tax": 5.34,
      "coupon": "FLASH_SALE",
    },
    items: [
      // MarktagEventItem list
    ],
  ),
);

Log Refund ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "Refund",
    metadata: {
      "currency": "USD",
      "value": 120,
      "transaction_id": "1234567890",
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
    items: [
      // MarktagEventItem list
    ],
  ),
);

Log Remove From Cart ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "RemoveFromCart",
    metadata: {
      "currency": "USD",
      "value": 120,
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
    items: [
      // Optional MarktagEventItem list
    ],
  ),
);
dart
Marktag.instance.logSearch("keyboard");

Log Share ​

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "Share",
    metadata: {
      "item_id": "1234567890",
      "method": "facebook",
      "custom_parameter_1": "value",
      "custom_parameter_2": "value",
    },
  ),
);

Log FCM Token ​

Send the user's Firebase Cloud Messaging (FCM) device token so Markopolo can deliver push notifications to users who have the app installed. Fire this event after the device generates a token and the user grants notification permission.

dart
Marktag.instance.logEvent(
  MarktagEvent(
    event: "Fcm",
    email: "user@email.com", // Optional
    phone: "xxxxxxxxxxx",    // Optional
    metadata: {
      "fcm_token": "fGc8x9abc...:APA91bF...", // Required
    },
  ),
);

Copyright © 2026 Markopolo AI