superfine_sdk 0.0.3

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

Summary

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

Table of contents

Quick start

• Getting started
  • Add the SDK to your project
  • [Android] Add permissions
• Integrate the SDK into your app
  • Basic setup
  • Superfine Logging

Sending event

• Revenue Event
• Linking Event
• Custom Event
• User Information
• Callback

Deep linking

• Callback

Push token

• Callback

Superfine Lifecycle

• Callback

---

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("[e-mail]");

---

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("[e-mail]");

---

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());