Swaarm SDK
Installation
To install the Swaarm SDK, add it to your Flutter project by running:
flutter pub add swaarm_sdk
Configuration
To configure the Swaarm SDK, initialize the client in your main.dart file using the
SwaarmClient.init(<domain>, <token>) method. This should be done after running your app:
import 'package:flutter/material.dart';
import 'package:swaarm_sdk/swaarm_sdk.dart';
void main() {
runApp(const MyApp());
SwaarmClient.init("example.swaarm.com", "<token>");
}
Replace "example.swaarm.com" with your Swaarm tracking domain and "<token>" with your specific
access token. During development, you can enable debugging with:
import 'package:flutter/material.dart';
import 'package:swaarm_sdk/swaarm_sdk.dart';
void main() {
runApp(const MyApp());
SwaarmClient.init("example.swaarm.com", "<token>", debug: true);
}
Usage
Automatic Event Tracking
The Swaarm SDK automatically tracks certain events:
- App Open Event: Fires every time the app is opened.
- Install Event: Fires the first time the app is opened after installation.
These events include enriched user data, such as the OS version, vendorId, and, if available, the IDFA (Identifier for Advertisers).
Note: On devices running iOS 14 and later, user consent is required to access the IDFA. This consent must be requested from a visible app interface. For more details, refer to this StackOverflow answer.
Custom Events
You can manually trigger custom events using the event and purchase methods.
Sending a Custom Event
The event method allows you to track specific user actions. It supports the following parameters:
typeId: The type of event you want to track (e.g., "registration").aggregatedValue: A numerical value that Swaarm aggregates in reports (e.g., number of items purchased).customValue: A free-form string value presented as-is in reports (e.g., specific details about the event).
SwaarmClient.event(
typeId: "registration",
aggregatedValue: 25.0,
customValue: "{\"email\": \"example@example.org\"}"
);
Tracking Purchases
The purchase method is used to track purchase-related events. It supports the following
parameters:
typeId: The type of purchase event (e.g., "subscription").revenue: The amount of revenue generated by the purchase.currency: The currency in which the revenue is reported (e.g., "USD").receiptOrToken: The receipt data, transaction ID, or token used to verify the purchase.androidPurchaseId: The purchase or subscription ID for Android transactions.
SwaarmClient.purchase(
typeId: "subscription",
revenue: 11.0,
currency: "USD",
receiptOrToken: "base64ReceiptDataOrTransactionIdOrToken",
androidPurchaseId: "purchaseOrSubscriptionID",
);
Deferred Deep Links
The Swaarm SDK supports deferred deep linking, allowing your app to respond to deep links that were clicked before the app was installed. When the app is opened for the first time, if a deferred deep link was clicked, and you have registered a callback for deep links, the SDK will invoke this callback. You can use this callback to navigate directly to specific pages or perform actions within your app.
To utilize this feature, register a DeferredDeepLinkCallback during the SDK initialization. Here's how you can implement this:
import 'package:flutter/material.dart';
import 'package:swaarm_sdk/swaarm_sdk.dart';
void main() {
runApp(MyApp());
SwaarmClient.init(
"example.swaarm.com",
"<token>",
deferredDeepLinkCallback: (String route) {
// Here you can handle the route, e.g. navigate to it
Navigator.pushNamed(context, route);
}
);
}
Attribution data
The Swaarm SDK periodically contacts the server to retrieve attribution data until valid data is received. You can access the currently available attribution data via the following property:
SwaarmClient.attributionData
You can also register a callback function which is invoked when successful attribution happens, as in the example below:
import 'package:flutter/material.dart';
import 'package:swaarm_sdk/swaarm_sdk.dart';
void main() {
runApp(const MyApp());
SwaarmClient.init(
"example.swaarm.com",
"<token>",
attributionCallback: (AttributionData attributionData) {
print("Received valid attribution data: $attributionData");
});
}
The schema of the AttributionData class is described below.
UML Diagram
+------------------------------------+
| AttributionData |
+------------------------------------+
| - offer: AttributionOffer? |
| - publisher: AttributionPublisher? |
| - ids: Ids? |
| - decision: PostbackDecision? |
+------------------------------------+
|
|
|------------------> +-------------------------+
| AttributionOffer |
+-------------------------+
| - id: String? |
| - name: String? |
| - lpId: String? |
| - campaignId: String? |
| - campaignName: String? |
| - adGroupId: String? |
| - adGroupName: String? |
| - adId: String? |
| - adName: String? |
+-------------------------+
|------------------> +-----------------------+
| AttributionPublisher |
+-----------------------+
| - id: String? |
| - name: String? |
| - subId: String? |
| - subSubId: String? |
| - site: String? |
| - placement: String? |
| - creative: String? |
| - app: String? |
| - appId: String? |
| - unique1: String? |
| - unique2: String? |
| - unique3: String? |
| - groupId: String? |
+-----------------------+
|------------------> +----------------------+
| Ids |
+----------------------+
| - installId: String? |
| - clickId: String? |
| - userId: String? |
+----------------------+
|------------------> +-----------------------+
| PostbackDecision |
+-----------------------+
| - passed |
| - failed |
+-----------------------+
Class: AttributionData
The AttributionData class contains information about the offer, publisher, IDs, and postback decision related to an attribution event.
Fields:
offer(AttributionOffer?): Information about the offer involved in the attribution event.publisher(AttributionPublisher?): Information about the publisher involved in the attribution event.ids(Ids?): Identifiers relevant to the attribution process.decision(PostbackDecision?): The decision outcome of the postback process, either passed or failed.
Class: AttributionOffer
The AttributionOffer class holds details about the offer involved in the attribution process.
Fields:
id(String?): The unique identifier for the offer.name(String?): The name of the offer.lpId(String?): Landing page ID for the offer.campaignId(String?): The unique identifier for the campaign associated with the offer.campaignName(String?): The name of the campaign.adGroupId(String?): The unique identifier for the ad group related to the offer.adGroupName(String?): The name of the ad group.adId(String?): The unique identifier for the ad related to the offer.adName(String?): The name of the ad.
Class: AttributionPublisher
The AttributionPublisher class holds details about the publisher responsible for serving the offer.
Fields:
id(String?): The unique identifier for the publisher.name(String?): The name of the publisher.subId(String?): The sub-identifier for tracking purposes.subSubId(String?): A secondary sub-identifier for tracking purposes.site(String?): The website or platform where the ad was displayed.placement(String?): The placement location of the ad on the website or platform.creative(String?): The creative used in the advertisement.app(String?): The application where the ad was displayed.appId(String?): The unique identifier for the application.unique1(String?): A unique identifier for tracking purposes.unique2(String?): A secondary unique identifier for tracking.unique3(String?): A tertiary unique identifier for tracking.groupId(String?): The external ID of the publisher as defined by the third party system (e.g. CRM, anti-fraud tool etc).
Class: Ids
The Ids class contains various identifiers related to the attribution process.
Fields:
installId(String?): The identifier for the installation of the app.clickId(String?): The identifier for the click that triggered the attribution process.userId(String?): The identifier for the user involved in the attribution process.
Enum: PostbackDecision
The PostbackDecision enum represents the possible outcomes of the postback process, determining whether an attribution event has passed or failed.
Values:
passed: The postback process was successful.failed: The postback process failed.