Integrating the Singular Plugin

To add the Singular plugin to your Flutter app, add the following lines to your pubspec.yaml file:

dependencies:
  singular_flutter_sdk: ^1.0.12

Then navigate to your project in the terminal and run the following:

flutter packages get

Additional Steps for Android

For Android apps, you need to add the Singular library to the dependencies list in app/build.gradle, as follows:

dependencies {
  implementation 'com.google.android.gms:play-services:6.5.87'
  implementation fileTree(dir: 'libs', include: ['*.jar'])
  implementation 'com.android.support:appcompat-v7:21.0.3'
  ...
}

If you have disabled transitive dependencies for the Singular SDK, add the following to your app's build.gradle.

implementation 'com.android.installreferrer:installreferrer:2.2'
implementation 'com.google.android.gms:play-services-appset:16.0.0'

If your app doesn't implement Google Play Services API 17.0.0 or higher, add the following dependency to your app's build.gradle:

implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0+'

Additional Steps for iOS

To use the Singular plugin, you have to add the AdServices framework.

Initializing the Singular SDK

The Singular SDK initialization code should be called every time your app is opened. It is a prerequisite to all Singular attribution functionality, and it also sends a new user session to Singular (sessions are used to calculate user retention).

The initialization code goes in your main app widget - the first one that loads when the app is opened. This widget has to be stateful, and the code has to be added in the widget's initState() method.

First, you have to create a SingularConfig object. The object contains your Singular SDK Key and Secret (which you can retrieve by logging into your Singular account and going to Developer Tools > SDK Keys).

Optionally, you can add settings to enable various SDK features. See the full list of options.

Example:

import 'package:singular_flutter_sdk/singular.dart';
  import 'package:singular_flutter_sdk/singular_config.dart';
  
  ...
  
  class MyHomePage extends StatefulWidget { 
      ...
  }
  
  class _MyHomePageState extends State<MyHomePage> {
      ...
      @ovveride 
            
      initState() {
              ...
              SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');
              config.customUserId = "test@test.com";
              Singular.start(config);
      }

Tracking Events

Singular can collect data about in-app events to help analyze the performance of your campaigns and measure KPIs. For example, your organization may want to collect data about user logins, registrations, tutorial completions, or leveling up in a gaming app.

Singular supports a variety of standard events. These commonly used events are often supported by ad networks for reporting and optimization. Another advantage is that when you use standard event names, Singular recognizes them automatically and adds them to the Events list without you having to define them manually. We recommend using standard events whenever possible.

The list of events sent to Singular (with the accompanying attributes) should be compiled by the UA/marketing/business team based on your organization's marketing KPIs. The business team can follow the guide at How to Track In-App Events: Guide For Singular Attribution Customers.

With each event you track, you can pass various attributes. See the recommended standard attributes per event.

In your code, send events to Singular using the event or eventWithArgs methods.

Example:

Singular.event(sngLogin);
Singular.eventWithArgs(eventName, {attributeName:attributeValue});

Tracking Revenue

Sending IAP Events

To let Singular track how much revenue your app is making, send IAP events to Singular. By sending the IAP event you also allow Singular to check the event verification data and make sure it's not fraudulent.

See the following example.

Note: This code snippet requires the Flutter IAP package at https://pub.dev/packages/in_app_purchase.

import 'package:singular_flutter_sdk/singular_iap.dart';
import 'dart:io' show Platform;
            
if (Platform.isIOS) {
  singularPurchase = new SingularIOSIAP(
    product.rawPrice.toStringAsFixed(2),
    product.currencyCode,
    purchase.productID,
    purchase.purchaseID,
    purchase.verificationData.serverVerificationData
  );
}
            
else if (Platform.isAndroid) {
  singularPurchase = new SingularAndroidIAP(
    product.rawPrice.toStringAsFixed(2),
    product.currencyCode,
    purchase.verificationData.serverVerificationData,
    purchase.verificationData.localVerificationData
  );
}
            
Singular.inAppPurchase(eventName, singularPurchase);

Alternative Method: Sending Custom Revenue Events

Singular also offers the option of reporting revenue by just sending a custom revenue event with a name and a revenue amount. Note that this method does not share the purchase receipt with Singular and therefore does not allow Singular to verify that it's a legitimate event.

For example:

Singular.customRevenue("MyCustomRevenue", "USD", 5.50);

Adding Ad Revenue Attribution Support

To add ad revenue attribution support using the Flutter SDK:

1. If you haven't done so yet, contact your Singular Customer Success Manager to enable ad revenue attribution for your account.

2. Add the appropriate code snippet to get ad revenue information from the mediation platform you use for ad revenue data.

   See code snippets in our Android SDK documentation.

3. Report the ad revenue to Singular using the following code:

   SingularAdData adData = SingularAdData("Medation_Platform","USD",0.05)
     .withNetworkName(networkName) //Optional
     .withAdType(adType) //Optional
     .withAdGroupType(adGroupType) //Optional
     .withImpressionId(impressionId) //Optional
     .withAdPlacementName(adPlacementName) //Optional
     .withAdUnitId(adUnitId) //Optional
     .withAdUnitName(adUnitName) //Optional
     .withAdGroupId(adGroupId) //Optional
     .withAdGroupName(adGroupName) //Optional
     .withAdGroupPriority(adGroupPriority) //Optional
     .withPrecision(precision) //Optional
      
   Singular.adRevenue(adData)

Implementing Deep Links

Deep links are links that open the app on the user's phone and send the user directly to a specific page or user experience, instead of just the app's main widget. Deep links are usually used in retargeting campaigns, aimed at users who already have the app on their phone but may not have engaged with it for a while. Singular supports deep linking through Singular Links.

Enabling Singular Links

To enable Singular Links in iOS and in Android, see Singular Links Prerequisites.

For Android support add the following code in the project's MainActivity.java file: 

import com.singular.flutter_sdk.SingularBridge;
  
@Override
protected void onNewIntent(@NonNull Intent intent) {
  super.onNewIntent(intent);
  SingularBridge.onNewIntent(intent);
}

import com.singular.flutter_sdk.SingularBridge;

override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
SingularBridge.onNewIntent(intent);
}

For iOS Support, in the project’s AppDelegate.m, add the following:

// Top of AppDelegate.m
            
  #import "SingularAppDelegate.h"
  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [GeneratedPluginRegistrant registerWithRegistry:self];
    [SingularAppDelegate shared].launchOptions = launchOptions;
    return [super application:application didFinishLaunchingWithOptions:launchOptions];
    }
  - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> *restorableObjects))restorationHandler {
    [[SingularAppDelegate shared] continueUserActivity:userActivity restorationHandler:restorationHandler];
    return YES;
    }
  - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
      [[SingularAppDelegate shared] handleOpenUrl:url options:options];
      return YES;
    }

import singular_flutter_sdk
  
override func application(_ application: UIApplication, didFinishLaunchingWithOptions
  launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
  GeneratedPluginRegistrant.register(with: self)
  if let singularAppDelegate = SingularAppDelegate.shared() {
    singularAppDelegate.launchOptions = launchOptions
  }
  return super.application(application, didFinishLaunchingWithOptions:
  launchOptions)
}

override func application(_ application: UIApplication, continue userActivity:
NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?)
-> Void) -> Bool {
  if let singularAppDelegate = SingularAppDelegate.shared() {
    singularAppDelegate.continueUserActivity(userActivity, restorationHandler:nil)
  }
  return true
}

override func application(_ app: UIApplication, open url: URL, options:
[UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
  if let singularAppDelegate = SingularAppDelegate.shared() {
    singularAppDelegate.handleOpen(url, options: options)
  }
  return true
}

Handling Singular Links

Use Singular's handler mechanism to read the details of the tracking link that led to the app being opened.

For example:

SingularConfig config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');

config.singularLinksHandler = (SingularLinkParams params) {
  String deeplink = params.deeplink;
  String passthrough = params.passthrough;
  bool isDeferred = params.isDeferred;
  // Add your code here to handle the deep link
});
          
Singular.init(config);

Adding SKAdNetwork Support

To enable SKAdNetwork tracking for your app, enable the skAdNetworkEnabled configuration option before initializing Singular.

Managed Mode (Recommended)

In managed mode, Singular manages the SKAdNetwork conversion value for you automatically, based on a conversion model of your choice that you can set up in the Singular web app. 

To learn more, see Understanding Singular's Conversion Value Management and the SKAdNetwork Model Configuration FAQ. For a step-by-step guide t using SKAdNetwork with Singular, see How to Get Started with SKAdNetwork.

To enable SKAdNetwork in managed mode, use the following code:

SingularConfig config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
config.skAdNetworkEnabled = true;
config.manualSkanConversionManagement = false;
Singular.init(config);

Manual Mode

If you already have your own strategy and tools for managing the SKAdNetwork conversion value, you can enable SKAdNetwork in manual mode.

SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');
config.skAdNetworkEnabled = true;
config.manualSkanConversionManagement = true;
Singular.init(config);

Then, to update the conversion value, use the following code:

ingular.skanUpdateConversionValue(conversionValue)

To track when the conversion value changes, use the following callback function:

config.conversionValueUpdatedCallback = (int conversionValue) {
  print('Received conversionValueUpdatedCallback: ' + conversionValue.toString());
};

To retrieve the current conversion value, use the following code:

Singular.skanGetConversionValue().then((conversionValue) {
  print('conversion value: ' + conversionValue.toString());
});

Tracking Uninstalls

To let Singular track app uninstalls, give Singular the APNS/FCM token, as in the following example:

// iOS
Singular.registerDeviceTokenForUninstall(apnsToken);
            
// Android
Singular.registerDeviceTokenForUninstall(fcmToken);