superfine_sdk - Dart API docs

Summary

This the Flutter SDK of Superfine™. You can read more about Superfine™ at https://docs.superfine.org.

Quick start

Getting started

These are the minimal steps required to integrate the Superfine SDK into your Flutter app.

Add the SDK to your project

You can add Superfine SDK to your Flutter app by adding following to your pubspec.yaml file:

dependencies:
  superfine_sdk: ^0.0.3

Then navigate to your project in the terminal and run:

flutter packages get

Note: If you are using Visual Studio Code to develop your app, upon editing pubspec.yaml, it will automatically run this command, so you don't need to run it manually.

`Android` Add permissions

Please add the following permissions, which the Superfine SDK needs, if they are not already present in your AndroidManifest.xml file for Android platform:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Integrate the SDK into your app

To start with, we'll set up basic session tracking.

Basic setup

Make sure to initialize Superfine SDK as soon as possible in your Flutter app (upon loading first widget in your app). You can initialize Superfine SDK like described below:

final superfineSettings = SuperfineSdkSettings(appId: "{YOUR_PROJECT_ID}", appSecret: "{YOUR_PROJECT_SECRET}", autoStart: true);
await SuperfineSDK.initialize(superfineSettings);

Replace {YOUR_PROJECT_ID} and {YOUR_PROJECT_SECRET} with your project id and your project secret. You can find these in your dashboard.

Superfine Logging

You can increase or decrease the amount of logs that you see during testing by setting logLevel member on your config instance with one of the following parameters:

superfineSettings.copyWith(logLevel: LogLevel.verbose); // enable all logs
superfineSettings.copyWith(logLevel: LogLevel.debug); // disable verbose logs
superfineSettings.copyWith(logLevel: LogLevel.info); // disable debug logs
superfineSettings.copyWith(logLevel: LogLevel.none); // disable all logs

Sending events

With Superfine, you can send various application events for conversions or other relevant activities on your application. Below are methods for different event types:

Revenue Event

logAdRevenue:

static Future<void> logAdRevenue(String source, double revenue, String currency, {String network = "", Map<String, dynamic>? networkData});

Description: Call this function to send ad revenue.

Parameters
`source`	String: Must not be null. The ID of the purchase.
`revenue`	double: Must not be null. Revenue from ads.
`currency`	String: Must not be null. The currency code (e.g., "USD", "EUR") for the price.
`network`	String: Nullable. The network name (optional).
`networkData`	Map<String, dynamic>: Nullable. The network data (optional).

Example:

await SuperfineSDK.logAdRevenue("source_name", 0.01, "USD", network: "ad_network",
          networkData: {"campaign": "summer_sale", "adGroup": "group1"});

logIAPInitialization:

static Future<void> logIAPInitialization(bool isSuccess);

Description: Call this function to send an in-app purchase initialization event.

Parameters
`isSuccess`	bool: Must not be null. A bool flag indicating whether the initialization of the in-app purchase system was successful.

Example:

await SuperfineSDK.logIAPInitialization(true);

logIAPRestorePurchase:

static Future<void> logIAPRestorePurchase();

Description: Call this function to send an in-app purchase restore purchase event.

| Parameters: None

Example:

await SuperfineSDK.logIAPRestorePurchase();

logIAPResult:

static Future<void> logIAPResult(String pack, double price, int amount, String currency, bool isSuccess);

Description: Call this function to send an in-app purchase result.

Parameters
`pack`	String: Must not be null. The identifier of the in-app purchase package.
`price`	double: Must not be null. The price of the in-app purchase.
`amount`	int: Must not be null. The quantity of the purchased item.
`currency`	String: Must not be null. The currency in which the transaction was made.
`isSuccess`	bool: Must not be null. A boolean flag indicating whether the transaction was successful.

Example:

await SuperfineSDK.logIAPResult("com.example.pack", 9.99, 1, "USD", true);

logIAPReceipt:

static Future<void> logIAPReceiptApple(String receipt);

Description: Call this function to send the receipt data for an in-app purchase made through Apple's App Store.

Parameters
`receipt`	String: Must not be null. The receipt data for the in-app purchase, provided as a string.

Example:

await SuperfineSDK.logIAPReceiptApple("sample_apple_receipt");

static Future<void> logIAPReceiptGoogle(String data, String signature);

Description: Call this function to send the receipt data for an in-app purchase made through Google Play Store.

Parameters
`data`	String: Must not be null. The purchase data string, which contains details about the purchase.
`signature`	String: Must not be null. The signature string, which is used to verify the integrity and authenticity of the purchase data.

Example:

await SuperfineSDK.logIAPReceiptGoogle("sample_google_data", "sample_signature")

static Future<void> logIAPReceiptAmazon(String userId, String receiptId);

Description: Call this function to send the receipt data for an in-app purchase made through Amazon's App Store.

Parameters
`userId`	String: Must not be null. The user ID associated with the Amazon account that made the purchase.
`receiptId`	String: Must not be null. The receipt ID for the in-app purchase.

Example:

await SuperfineSDK.logIAPReceiptAmazon("sample_user_id", "sample_receipt_id")

static Future<void> logIAPReceiptRoku(String transactionId);

Description: Call this function to send the receipt data for an in-app purchase made through Roku's platform.

Parameters
`transactionId`	String: Must not be null. The transaction ID for the in-app purchase.

Example:

await SuperfineSDK.logIAPReceiptRoku("sample_transaction_id");

static Future<void> logIAPReceiptWindows(String receipt);

Description: Call this function to send the receipt data for an in-app purchase made through the Windows Store.

Parameters
`receipt`	String: Must not be null. The receipt data for the in-app purchase, provided as a string.

Example:

await SuperfineSDK.logIAPReceiptWindows("sample_windows_receipt");

static Future<void> logIAPReceiptFacebook(String receipt);

Description: Call this function to send the receipt data for an in-app purchase made through Facebook's platform.

Parameters
`receipt`	String: Must not be null. The receipt data for the in-app purchase, provided as a string.

Example:

await SuperfineSDK.logIAPReceiptFacebook("sample_facebook_receipt");

static Future<void> logIAPReceiptUnity(String receipt);

Description: Call this function to send the receipt data for an in-app purchase made through Unity's platform.

Parameters
`receipt`	String: Must not be null. The receipt data for the in-app purchase, provided as a string.

Example:

await SuperfineSDK.logIAPReceiptUnity("sample_unity_receipt");

static Future<void> logIAPReceiptAppStoreServer(String transactionId);

Description: Call this function to send the receipt data for an in-app purchase verified through Apple's App Store server.

Parameters
`transactionId`	String: Must not be null. The transaction ID for the in-app purchase.

Example:

await SuperfineSDK.logIAPReceiptAppStoreServer("sample_transaction_id_app_store");

static Future<void> logIAPReceiptGooglePlayProduct(String productId, String token);

Description: Call this function to send the receipt data for an in-app purchase made through Google Play.

Parameters
`productId`	String: Must not be null. The product ID of the purchased item.
`token`	String: Must not be null. The purchase token, provided by Google Play after a successful purchase.

Example:

await SuperfineSDK.logIAPReceiptGooglePlayProduct("product_id", "token");

static Future<void> logIAPReceiptGooglePlaySubscription(String subscriptionId, String token); static Future<void> logIAPReceiptGooglePlaySubscriptionV2(String token);

Description: Call these functions to send the receipt data for a subscription purchase made through Google Play.

Parameters
`productId`	String: Must not be null. The product ID of the purchased item.
`token`	String: Must not be null. The purchase token, provided by Google Play after a successful purchase.

Example:

await SuperfineSDK.logIAPReceiptGooglePlaySubscription("subscription_id", "token");
// or
await SuperfineSDK.logIAPReceiptGooglePlaySubscriptionV2("subscription_token");

logCryptoPayment:

static Future<void> logCryptoPayment(String pack, double price, int amount, {String currency = "ETH", String chain = "ethereum"});

Description: Call this function to send your custom events.

Parameters
`pack`	String: Must not be null. The identifier of the package or item being purchased..
`price`	double: Must not be null. The price of the item or package in terms of the specified cryptocurrency.
`amount`	int: Must not be null. The quantity of the purchased item.
`currency`	String: Default is ETH. The type of cryptocurrency used for the transaction (optional).
`chain`	String: Default is ethereum. The blockchain network used for the transaction (optional).

Example:

await SuperfineSDK.logCryptoPayment("crypto_pack", 0.05, 1, currency: "ETH", chain: "ethereum");

Linking Event

logAccountLink:

static Future<void> logAccountLink(String id, String type, {String? scopeId, String? scopeType});

Description: Call this function when you want to link the user with another identity.

Parameters
`id`	String: Must not be null. This is your user ID.
`type`	String: Must not be null. Type of identity. Supports "google", "facebook", "twitter", etc.
`scopeId`	String: Nullable. Identifier for the scope. Examples: Google Play Game Service Project ID, Google Play Developer Account ID, etc.
`scopeType`	String: Nullable. Type of the scope. Examples: "game", "developer", etc.

Example:

await SuperfineSDK.logAccountLink("8e46122c-3cbd-4da4-8a37-b7f8c8e46687", "superfine");

We also support various functions:

static Future<void> logFacebookLink(String userId);
static Future<void> logInstagramLink(String userId);
static Future<void> logAppleLink(String userId);
static Future<void> logAppleGameCenterLink(String gamePlayerId);
static Future<void> logAppleGameCenterTeamLink(String teamPlayerId);
static Future<void> logGoogleLink(String userId);
static Future<void> logGooglePlayGameServicesLink(String gamePlayerId);
static Future<void> logGooglePlayGameServicesDeveloperLink(String developerPlayerKey);
static Future<void> logLinkedInLink(String personId);
static Future<void> logMeetupLink(String userId);
static Future<void> logGitHubLink(String userId);
static Future<void> logDiscordLink(String userId);
static Future<void> logTwitterLink(String userId);
static Future<void> logSpotifyLink(String userId);
static Future<void> logMicrosoftLink(String userId);
static Future<void> logLINELink(String userId);
static Future<void> logVKLink(String userId);
static Future<void> logQQLink(String openId);
static Future<void> logQQUnionLink(String unionId);
static Future<void> logWeChatLink(String openId);
static Future<void> logWeChatUnionLink(String unionId);
static Future<void> logTikTokLink(String openId);
static Future<void> logTikTokUnionLink(String unionId);
static Future<void> logWeiboLink(String userId);

logAccountUnlink:

static Future<void> logAccountUnlink(String type);

Description: Call this function when you want to unlink the user with external identity.

Parameters
`type`	String: Must not be null. Type of identity. Supports "google", "facebook", "twitter", etc.

Example:

await SuperfineSDK.logAccountUnlink("superfine");

We also support various functions:

static Future<void> logFacebookUnlink();
static Future<void> logInstagramUnlink();
static Future<void> logAppleUnlink();
static Future<void> logAppleGameCenterUnlink();
static Future<void> logGoogleUnlink();
static Future<void> logGooglePlayGameServicesUnlink();
static Future<void> logLinkedInUnlink();
static Future<void> logMeetupUnlink();
static Future<void> logGitHubUnlink();
static Future<void> logDiscordUnlink();
static Future<void> logTwitterUnlink();
static Future<void> logSpotifyUnlink();
static Future<void> logMicrosoftUnlink();
static Future<void> logLINEUnlink();
static Future<void> logVKUnlink();
static Future<void> logQQUnlink();
static Future<void> logWeChatUnlink();
static Future<void> logTikTokUnlink();
static Future<void> logWeiboUnlink();

linkWallet:

static Future<void> logWalletLink(String wallet, {String type = "ethereum"});

Description: Call this function when you want to link the user's wallet address.

Parameters
`wallet`	String: Must not be null. The wallet address you want to log the linking event for.
`type`	String: Default is Ethereum. Type of the wallet (optional).

Example:

await SuperfineSDK.logWalletLink("0x50460c4cd74094cd591455cad457e99c4ab8be0", type: "eth");

unlinkWallet:

static Future<void> logWalletUnlink(String wallet, {String type = "ethereum"});

Parameters
`wallet`	String: Must not be null. The wallet address you want to log the linking event for.
`type`	String: Default is Ethereum. Type of the wallet (optional).

Example:

await SuperfineSDK.logWalletUnlink("0x50460c4cd74094cd591455cad457e99c4ab8be0", type: "eth");

Custom Event

static Future<void> log(String eventName, {dynamic data, EventFlag eventFlag = EventFlag.none});

Description: Call this function to send your custom events.

Parameters
`eventName`	String: Must not be null. The name of your event.
`eventFlag`	EventFlag: Default is `EventFlag.none`. Flag of the event.
`data`	dynamic: Must not be null. Value of the event. Supported types: int, String, Map.

Example:

await SuperfineSDK.log("sample_event_string", data: "Event data string");
await SuperfineSDK.log("sample_event_int", data: 123);
await SuperfineSDK.log("sample_event_map", data: {"key": "value"});

static Future<void> logCustomEvent(SuperfineSDKEvent event);

Description: Call this function to send your custom events.

Parameters
`event`	SuperfineSDKEvent: Must not be null. Represents your custom event object.

Example:

SuperfineSDKEvent customEvent = SuperfineSDKEvent(
    eventName: "custom_event_name",
    revenue: 0.01,
    currency: "USD",
    value: "something",
    eventFlag: EventFlag.none);
await SuperfineSDK.logCustomEvent(customEvent);

static Future<void> logCache(SuperfineSDKEvent event);

Description: Call this function to send your custom events before initialize SDK

Parameters
`event`	SuperfineSDKEvent: Must not be null. Represents your custom event object.

Example:

SuperfineSDKEvent cacheEvent = SuperfineSDKEvent(
    eventName: "cache_event_name",
    revenue: 0.01,
    currency: "USD",
    value: "something",
    eventFlag: EventFlag.cache);
await SuperfineSDK.logCache(cacheEvent);

User Information

static Future<void> addUserPhoneNumber(int countryCode, String number);

Description: Call this function to add user phone number.

Parameters
`countryCode`	int: Must not be null and must be greater than 0. The country code.
`number`	String: Must not be null or empty. The phone number.

Example:

await SuperfineSDK.addUserPhoneNumber(1, "555-1234");

static Future<void> removeUserPhoneNumber(int countryCode, String number);

Description: Call this function to remove user phone number.

Parameters
`countryCode`	int: Must not be null and must be greater than 0. The country code.
`number`	String: Must not be null or empty. The phone number.

Example:

await SuperfineSDK.removeUserPhoneNumber(1, "555-1234");

static Future<void> addUserEmail(String email);

Description: Call this function to add the user's email address.

Parameters
`email`	String: Must not be null. The email address of the user.

Example:

await SuperfineSDK.addUserEmail("user@example.com");

static Future<void> removeUserEmail(String email);

Description: Call this function to remove the user's email address.

Parameters
`email`	String: Must not be null. The email address of the user.

Example:

await SuperfineSDK.removeUserEmail("user@example.com");

static Future<void> setUserName({String? firstName, String? lastName});

Description: Call this function to set the user's name.

Parameters
`firstName`	String: Must not be null. The user's first name.
`lastName`	String: Must not be null. The user's last name.

Example:

await SuperfineSDK.setUserName(firstName: "John", lastName: "Doe");

static Future<void> setUserCity(String city);

Description: Call this function to set the user's city.

Parameters
`city`	String: Must not be null. City of the user.

Example:

await SuperfineSDK.setUserCity("San Francisco");

static Future<void> setUserState(String state);

Description: Call this function to set the user's state.

Parameters
`state`	String: String not be null. State of the user.

Example:

await SuperfineSDK.setUserState("California");

static Future<void> setUserCountry(String country);

Description: Call this function to set the user's country.

Parameters
`country`	String: Must not be null. Country of the user.

Example:

await SuperfineSDK.setUserCountry("United States");

static Future<void> setUserZipCode(String zipCode);

Description: Call this function to set the user's zip code.

Parameters
`zipCode`	String: Must not be null. Zip code of the user.

Example:

await SuperfineSDK.setUserZipCode("94103");

static Future<void> setUserDateOfBirth({int? day, int? month, int? year});

Description: Call this function to set the user's date of birth.

Parameters
`day`	int: Nullable. User's day of birth.
`month`	int: Nullable. User's month of birth.
`year`	int: Nullable. User's year of birth.

Example:

await SuperfineSDK.setUserDateOfBirth(day: 1, month: 1, year: 2000);

static Future<void> setUserGender(UserGender gender);

Description: Call this function to set the user's gender.

Parameters
`gender`	UserGender: Must not be null. The gender of the user, including `UserGender.male` and `UserGender.female`.

Example:

await SuperfineSDK.setUserGender(UserGender.male);

Callback

The Superfine SDK provides the mechanism you need to determine whether an event was sent:

SuperfineSDK.registerSendEventListener((jsonEvent) {
        print("[Superfine SDK] On sent event: $jsonEvent");
      });

Deep Linking

Callback

The Superfine SDK offers you the mechanism you need to obtain information about the deep link content:

SuperfineSDK.registerDeepLinkingListener((url) {
        print("[Superfine SDK] Received deeplink: $url");
      });

Push Token

Callback

The Superfine SDK offers you the mechanism you need to obtain information about when the device token is set:

SuperfineSDK.registerPushTokenListener((token) {
        print("[Superfine SDK] Received token: $token");
      });

Superfine Lifecycle

Callback

The Superfine SDK offers the necessary mechanisms to obtain information about Superfine's lifecycle.

class SuperfineSDKLifecycleListenerImplementation
    extends SuperfineSdkLifeCycleListener {
  @override
  void onPause() {
    print("[Superfine SDK] onPause");
  }

  @override
  void onResume() {
    print("[Superfine SDK] onResume");
  }

  @override
  void onStart() {
    print("[Superfine SDK] onStart");
  }

  @override
  void onStop() {
    print("[Superfine SDK] onStop");
  }
}
SuperfineSDK.registerSuperfineSDKLifecycleListener(
          SuperfineSDKLifecycleListenerImplementation());

Summary

Table of contents

Quick start

Sending event

Deep linking

Push token

Superfine Lifecycle

Quick start

Getting started

Add the SDK to your project

`Android` Add permissions

Integrate the SDK into your app

Basic setup

Superfine Logging

Sending events

Revenue Event

logAdRevenue:

logIAPInitialization:

logIAPRestorePurchase:

logIAPResult:

logIAPReceipt:

logCryptoPayment:

Linking Event

logAccountLink:

logAccountUnlink:

linkWallet:

unlinkWallet:

Custom Event

User Information

Callback

Deep Linking

Callback

Push Token

Callback

Superfine Lifecycle

Callback

Libraries

superfine_sdk package

Summary

Table of contents

Quick start

Sending event

Deep linking

Push token

Superfine Lifecycle

Quick start

Getting started

Add the SDK to your project

Android Add permissions

Integrate the SDK into your app

Basic setup

Superfine Logging

Sending events

Revenue Event

logAdRevenue:

logIAPInitialization:

logIAPRestorePurchase:

logIAPResult:

logIAPReceipt:

logCryptoPayment:

Linking Event

logAccountLink:

logAccountUnlink:

linkWallet:

unlinkWallet:

Custom Event

User Information

Callback

Deep Linking

Callback

Push Token

Callback

Superfine Lifecycle

Callback

Libraries

superfine_sdk package

`Android` Add permissions