Mobile SDK: Flutter Integration Guide – Help Center

Follow the steps in the Installation section to include the Wunderkind SDK in your project.
Initialize the SDK in your project with the steps defined under the Usage section.
Replace WEBSITE_ID with your website ID in the main SDK's initialize function and make sure to set isDebugMode flag to true both in development and testing environments.
[Optional but preferred] Request permissions within your app for location and MAID (IDFA/AAID).

3. Installation

This module is intended to be used alongside Flutter and as such, basic knowledge of core concepts as well as minimum experience is expected. Please refer to this getting started tutorial, should you wish to brush up.

It it also expected to have Xcode and/or Android Studio installed and setup in your working environment.

3.1 Android Ad Id permission configuration

Before proceeding further please ensure that you have a corresponding permission for “Google Advertising Id” (Ad Id) if your Android application project targets latest Android SDK 33.

Such a permission should be set in app’s AndroidManifest.xml file:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="XXXYYYZZZ">
...
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
...
<application
android:label="XXXYYYZZZ"
...
</application>
</manifest>

If you decide to opt-out of Ad Id tracking, please refer to corresponding section below.

3.2 Flutter SDK manual installation

As the Flutter SDK is a private SDK we only support manual SDK integration. Please, follow below steps to manually integrate Wunderkind Flutter SDK:

Download the latest 1.1.0 SDK archive from this link.
Unarchive folder, rename it to be wunderkind_sdk and paste it in the root directory of your Flutter project.
Open pubspec.yaml and specify wunderkind_sdk local dependency as it is done below:

dependencies:
wunderkind_sdk:
path: wunderkind_sdk

3.3 iOS Podfile update

Since Wunderkind Flutter SDK utilizes Wunderkind iOS SDK under the hood, we need to properly integrate the latter one. Wunderkind iOS SDK is stored in Wunderkind’s Google Cloud Storage, hence you need to attach a link to Wunderkind iOS SDK’s podspec in appropriate place.

Navigate to iOS/Podfile file and open it.
At the end of target 'Runner' just before end line please add corresponding line:

...
target 'Runner' do
use_frameworks!
...
// Please add this line
pod 'Wunderkind', podspec: 'https://storage.googleapis.com/wunderkind-ios-sdk/1.1.0.podspec'
end
...

3.4 Android Maven

Since Wunderkind Flutter SDK utilizes Wunderkind Android SDK under the hood, you’ll find below the steps required to install the Wunderkind Android SDK which is hosted in Google Platform's Artifact registry.

Navigate to android/app/build.gradle and ensure that URL to Wunderkind Android SDK is added under android/repositories/maven section.

android {
 repositories {
   maven {
     url "https://us-central1-maven.pkg.dev/bx-production-coreapi/wunderkind-sdk-android"
   }
 }
}

3.5 Installation conclusion

Run flutter pub get and build your project to run on iOS or Android. You should be good to go!

4. Usage

In order to allow your app to track events, please follow the steps highlighted in this section.

4.1 Import the Wunderkind SDK to your project.

import 'package:wunderkind_sdk/wunderkind.dart';
import 'package:wunderkind_sdk/classes/screen_type.dart';
// etc...

4.2 SDK Initialization

Initialize SDK with your WEBSITE_ID (If you don't know your WEBSITE_ID, please contact our support team to resolve this issue), and set a corresponding environment configuration isDebugMode (details below).

This step is required, otherwise the SDK won't be initialized properly and event tracking will be disabled.

💬By default debug mode is disabled, but setting isDebugMode to true allows you to verify events tracking functionality in a debug environment. Please do not forget to set to false before going live in production.

⚠️Set isDebugMode to false before promoting live in production.

 Wunderkind().initialize(WEBSITE_ID, isDebugMode);

4.3 Opting Users Out of Tracking

Client-side tracking of user data may be enabled/disabled by controlling a userʼs opt-in/out state. The opt-in/out state of a user is controlled by an opt-out flag that affects thge user's device information.

💬User information is tracked by default - A user must therefore explicitly opt-out to disable tracking.

4.3.1 Context Information Tracking

The Wunderkind SDK collects device/context specific information, which include:

Device Information:
- operating system name
- operating system version
- device model
- screen resolution
- device type
App Information:
- installation date
- bundle identifier
- version number
- build number

Users may opt-in/out of context tracking and this may be set through the isContextInfoTrackingEnabled property, which is enabled by default.

Wunderkind().setContextInfoTrackingEnabled(isEnabled)

4.4 Track Events

⚠️It’s imperative that SDK functions be only called once for a single application event. Duplicate calls may occur when using inheritance patterns and accidental calls to the same SDK functions from parent and child objects simultaneously.

💬Please refer to the Wunderkind SDK Reference section for more information about classes and types that are used in SDK's API.

💬Underlying data points gathered by the Wunderkind SDK may be reviewed by using proxy applications such as Charles or Proxyman and through the use of request interceptions. This will help you to validate that events are sent with the expected arguments provided via the API functions. Also note that events are sent to the backend every 1 minute.

Please also refer to the Logging section below to customize your project's debug logs section to review Wunderkind SDK's expected results (initialization result, events saving and sending response).

The following is a list of public functions in Wunderkind class that may be used for tracking events.

4.4.1 Screen view event

Overview

This event should be triggered when a user navigates to a new screen, within the app.

Wunderkind().trackScreenViewEvent(url: string, screenType: ScreenType)

💬url property is required to be non-null otherwise this event will not be tracked. If you cannot provide corresponding screen's URL, please use your default home webpage URL.

💬type is a required Enum. There is no need to call trackScreenView if the page does not fall into one of the Enum's types.

⚠️This event should only be called once per page navigation. We recommend calling trackScreenView API when the page is presented to the user (componentDidMount + didFocus), and not when page is initialized and not yet presented.

Example Implementation:

class _HomePageState extends State {
 @override
 Widget build(BuildContext context) {
 // Pass here screen's URL or your default home webpage URL.
 Wunderkind().trackScreenViewEvent("https://www.your-webpage.com/search", ScreenType.search);
 }
}

4.4.2 Empty cart event

Overview

This event should be triggered when a user empties a cart.

⚠️This event should only be triggered when a user has items in their cart and empties it. Not every time a user opens their empty cart.

Wunderkind().trackEmptyCartEvent()

Example Implementation:

class _CheckoutPageState extends State {
 ..

 Future cartBecameEmpty() async {
 // This event should only be triggered when a user has items in their cart and empties it.
 // Not every time a user opens their empty cart.
 Wunderkind().trackEmptyCartEvent();
 };
}

4.4.3 View item event

Overview

This event should be triggered when a user views an item.

 Wunderkind().trackViewItemEvent(itemId: string, groupId: string)

💬itemId, groupId properties are required to be non-empty otherwise this event will not be tracked.
groupId represents a group of similar items. For example, a shirt will have the same groupId for all variations of that shirt (different sizes/colors, etc). I.e. each size/color combo will have a different itemId but the same groupId.

💬We recommend calling the trackViewItem API when the product screen is presented to the user (componentDidMount + didFocus) and not when screen is initialized and not yet presented.

Example Implementation:

class _ItemPageState extends State<UserPage> {
@override
Widget build(BuildContext context) {
Wunderkind().trackViewItemEvent("8989", ""1")
}
}

4.4.4 Select SKU event

This event is triggered when a user selects specific product attributes (e.g. color, size, etc…) and contains SKU details that were selected.

Wunderkind().trackSelectSkuEvent(groupId: string, feedId: string)

💬groupId and feedId properties are required to be non-empty otherwise this event will not be tracked.
groupId represents a group of similar items. For example, a shirt will have the same groupId for all variations of that shirt (different sizes/colors, etc). I.e. each size/color combo will have a different feedId but the same groupId.

Example Implementation:

class _ItemPageState extends State<ScreenPage> {
..

Future<void> skuSelected() async {
Wunderkind().trackSelectSkuEvent("20000469213", "02")
};
}

4.4.5 Add to cart event

Overview

This event is triggered when a user adds an item to their cart.

 Wunderkind().trackAddToCartEvent(itemId: string)

💬itemId property is required to be non-empty otherwise this event will not be tracked.

Example Implementation:

class _ItemPageState extends State<ScreenPage> {
..

Future<void> itemAddedToCart() async {
Wunderkind().trackAddToCartEvent("7727082")
};
}

4.4.6 View category event

Overview

This event is triggered when a user views the category screen

Wunderkind().trackViewCategoryEvent(productCategory: ProductCategory)

💬productCategory property is required to be non-null otherwise this event will not be tracked. If you cannot provide corresponding category’s URL, please pass your default home webpage URL.

Please refer to Product Category section to learn more about expected types and values to be sent.

Example Implementation:

class _CategoryScreenState extends State<ScreenPage> {
..

Future<void> CategoryLoadedSuccess() async {
Wunderkind().trackViewCategoryEvent(ProductCategory(
"https://www.mywebsite.com/top-level-category/leaf-category", "Fine", ["01","02","03"])
};
}

4.4.7 View search event

Overview

This event is triggered when a user views the category screen.

Wunderkind().trackViewSearchEvent(productCategory: ProductCategory)

💬productCategory property is required to be non-null otherwise this event will not be tracked. If you cannot provide corresponding search’s URL, please pass your default home webpage URL

Example Implementation:

class _SeachPageState extends State<ScreenPage> {
..

Future<void> SearchLoadedSuccess() async {
Wunderkind().trackViewSearchEvent(ProductCategory(
"https://www.your-webpage.com/search?input=coconut, "coconut", ["01","02","03"])
};
}

4.4.8 Logged in event

Overview

This event is triggered when a user explicitly successfully signed in to their app. This event is also triggered when a user signed up to their app.

Wunderkind().trackLoggedInEventWithPhone(email: string, phone: string)

💬email property is required to be non-empty otherwise this event will not be tracked.

💬Please pass phone in the following format +(country code)(phone number) Example: +13305851212

Example Implementation:

class _LoginPageState extends State {

..

Future<void> LoginSuccess() async {
Wunderkind().trackLoggedInEventWithPhone("user@gmail.com", '+999888777666');
};
}

4.4.9 LoggedOut Event

Overview

This event is called when a user logs out of the application.

Wunderkind().trackLoggedOutEvent()

Example Implementation:

class _LoggedoutPageState extends State<ScreenPage> {
Future<void> Loggedout() async {
Wunderkind().trackLoggedOutEvent()
};
}

4.4.10 Text Opt In Event

Overview

This event is triggered when a user opts in to text messaging.

💬Pass null for languageCode, unless the desired language is French then pass a String with value “fr”

💬Please pass phone in the following format +(country code)(phone number)
Example: +13305851212

Wunderkind().trackTextOptIn(phoneNumber: string, languageCode: string?)

Example Implementation:

class _CollectPNPageState extends State<ScreenPage> {
Future<void> PNEntereted() async {
Wunderkind().trackTextOptIn("3802128821", "fr")
};
}

4.4.11 Purchase event

Overview

This event is triggered when a user purchases an item and completes their order.

Wunderkind().trackPurchaseEvent(order: Order)

💬order property is required to be non-null otherwise this event will not be tracked.

⚠️Please note that due to the importance of the Purchase event, it’s imperative that all of its attributes (Invoice, Customer, Product, Order) be correctly set.

⚠️Should purchase event attributes not be entered correctly, the following error may be generated in your project’s logs:
Unfortunately, event "Purchase" hasn't been tracked since you have provided a nullable parameter or a not valid one.
Please ensure that all arguments sent to the SDK are correctly entered and contact the Wunderkind SDK team, should you need any help.

Example Implementation:

class _CheckoutPageState extends State {
 ..

 Future CheckoutSuccess() async {
 var customer = Customer(email: "customer@gmail.com", phone: "+12223334445");
 var invoice = Invoice(58, 818.99, Currency.ttry, 22, 99.99);
 var product = Product("ProductSKUAlpha", 34.0, 33, "ProductIDAlpha");
 var product2 = Product("ProductSKUBeta", 3422, 3322, "ProductIDBeta");
 var prList = [product, product2];
 var coupons = ["Coupon Red", "Coupon Blue", "Coupon Purple"];
 var myOrder = Order("Test Order ID", invoice, customer, prList,
 "Test Order Goal", "Test Order Payment Method", coupons);
 Wunderkind().trackPurchaseEvent(myOrder);
 };
}

4.5 Logging

The Wunderkind SDK provides logging capabilities in order to report on events collected and are useful to validate user data.

Setting logLevel property to debug will allow you to trace data going through the Wunderkind SDK.

Wunderkind.setLoggingLevel(LogLevel.debug);

Setting logLevel property to none allows you to disable logging.

Wunderkind.setLoggingLevel(LogLevel.none);

💬logLevel default value is info, which notifies you about events deemed to be important (Activation, Validation Errors, etc.)

5. Wunderkind SDK Reference

5.1 Classes

Product Category

class ProductCategory {
String url;
String title;
List<String> itemIds;
}

💬title, url, itemIds properties are required to be non-empty, non-null and non-null, respectively. Failure to do so will prevent Wunderkind from tracking this event.
Note: If you cannot provide corresponding product category's URL, please pass your default home webpage URL.

Invoice

class Invoice {
double amount;
double shipping;
Currency currency;
double tax;
double? totalDiscount;
}

💬amount, tax, shipping properties are required to be greater than or equal to 0.0 otherwise this event will not be tracked. Also, iftotalDiscount property is not null, it must be greater than or equal to 0.0.

Customer

class Customer {
String email;
String phone;
}

💬emailis required to be non-empty otherwise this event will not be tracked.

💬Please pass phone in the following format +(country code)(phone number) Example: +13305851212

Product

class Product {
String skuId;
double price;
int quantity;
String productId;
}

💬productId, skuId properties are required to be non-empty and price, quantity properties are required to be greater than or equal to 0 otherwise this event will not be tracked.

Order

class Order {
String orderId;
Invoice invoice;
Customer customer;
List<Product> products;
String goal;
String paymentMethod;
List<String>? coupons;
}

💬orderId, goal, products properties are required to be non-empty otherwise this event will not be tracked. Also, if paymentMethod or coupons properties are not null, they must be non-empty.

5.2 Enums

Screen Type

enum ScreenType {
home,
product,
category,
search,
cart,
article,
gallery,
checkout,
}

Currency

enum Currency {
USD,
KRW,
AED,
LTL,
ARS,
MAD,
AUD,
MXN,
BGN,
MYR,
BOB,
NOK,
BRL,
NZD,
CAD,
PEN,
CHF,
PHP,
CLP,
PKR,
CNY,
PLN,
COP,
RON,
CZK,
RSD,
DKK,
RUB,
EGP,
SAR,
EUR,
SEK,
GBP,
SGD,
HKD,
THB,
HRK,
TRY,
HUF,
TWD,
IDR,
UAH,
ILS,
VEF,
INR,
VND,
JPY,
ZAR,
}

LogLevel

enum LogLevel {
none,
debug,
info
}

6. Change Log

Version	Release Date	Details
1.4.1	11.04.2024	• New events: TextOptIn, Loggedin- Phone Parameter • Location/AAID tracking Removed • remove visitDuration external variable • removesetMetricsInterval • remove trackingEnablement variables • phone number required to be Long • Customer.createCustomer()required,isHashedremoved • Remove LoginMethod Parameter, ExistingLoggedIn Methods
1.1.0	01.10.2024	Bug Fixes
1.0.8	10.04.2023	Flutter SDK Launch

7. License

Distributed under the MIT License. To view the full license, visit http://www.wunderkind.co/legal/sdklicense-agreement

Flutter SDK

1. SDK Stats

2. Integration Steps

3. Installation

3.1 Android Ad Id permission configuration

3.2 Flutter SDK manual installation

3.3 iOS Podfile update

3.4 Android Maven

3.5 Installation conclusion

4. Usage

4.1 Import the Wunderkind SDK to your project.

4.2 SDK Initialization

4.3 Opting Users Out of Tracking

4.4 Track Events

4.5 Logging

5. Wunderkind SDK Reference

5.1 Classes

5.2 Enums

6. Change Log

7. License

Related articles