singular_flutter_sdk

You can add Singular Plugin to your Flutter app by adding following to your pubspec.yaml file:

dependencies:
  singular_flutter_sdk: ^1.9.0

Then navigate to your project in the terminal and run:

flutter packages get

iOS dependency managers

The iOS plugin supports both CocoaPods and Swift Package Manager, so no extra setup is required either way. CocoaPods supports iOS 12 and above; Swift Package Manager requires iOS 13, the minimum Flutter itself declares for that path.

Before you initialize the Singular SDK, you have to create a SingularConfig object. The object contains your API key and API secret for the Singular SDK. Optionally, you can add settings to enable various SDK features.

Example:

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';

SingularConfig config = new SingularConfig('API_KEY', 'API_SECRET');
config.customUserId = "test@test.com";
Singular.start(config);

You can send events to Singular using the event and eventWithArgs methods.

Example:

Singular.event(eventName);

Singular.eventWithArgs(eventName, {"level-up":"5"});

Report a custom event to Singular

Example:

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

Report an IAP event to Singular

Example:

import 'package:singular_flutter_sdk/singular_iap.dart';

 singularPurchase = new SingularIOSIAP(
   product.price,
   product.currencyCode,
   purchase.productId,
   purchase.purchaseId,
   purchase.verificationData.serverVerificationData
 );

 singularPurchase = new SingularAndroidIAP(
   product.price,
   product.currencyCode,
   purchase.singature,
   purchase.verificationData.serverVerificationData
 );

Singular.inAppPurchase(eventName, singularPurchase);

Under the scene lifecycle the deep link callbacks move from the AppDelegate to the SceneDelegate, so the same Singular calls go there instead. Note that a link that launched the app arrives in connectionOptions, not in launchOptions.

Swift:

import singular_flutter_sdk

override func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
    if let userActivity = connectionOptions.userActivities.first {
        SingularAppDelegate.shared()?.userActivity = userActivity
    } else if let urlContext = connectionOptions.urlContexts.first {
        SingularAppDelegate.shared()?.openURL = urlContext.url
    }
    super.scene(scene, willConnectTo: session, options: connectionOptions)
}

override func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    SingularAppDelegate.shared()?.continueUserActivity(userActivity, restorationHandler: nil)
    super.scene(scene, continue: userActivity)
}

override func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    if let url = URLContexts.first?.url {
        SingularAppDelegate.shared()?.handleOpen(url, options: nil)
    }
    super.scene(scene, openURLContexts: URLContexts)
}

Objective-C:

// Top of the SceneDelegate.m
#import "SingularAppDelegate.h"

- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {

    NSUserActivity *userActivity = connectionOptions.userActivities.anyObject;
    UIOpenURLContext *urlContext = connectionOptions.URLContexts.anyObject;

    if (userActivity) {
        [SingularAppDelegate shared].userActivity = userActivity;
    } else if (urlContext) {
        [SingularAppDelegate shared].openURL = urlContext.URL;
    }
    [super scene:scene willConnectToSession:session options:connectionOptions];
}

- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity {

    [[SingularAppDelegate shared] continueUserActivity:userActivity restorationHandler:nil];
    [super scene:scene continueUserActivity:userActivity];
}

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {

    [[SingularAppDelegate shared] handleOpenUrl:URLContexts.anyObject.URL options:nil];
    [super scene:scene openURLContexts:URLContexts];
}

The snippets above assume your scene delegate subclasses FlutterSceneDelegate. If it implements UIWindowSceneDelegate directly, use the same bodies without the override / super calls.

Android Prerequisites

Java:

In the project’s MainActivity.java, add the following:

import com.singular.flutter_sdk.SingularBridge;

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

Kotlin:

import com.singular.flutter_sdk.SingularBridge;

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

Starting with version 1.0.15 of the Singular Flutter SDK, skAdNetworkEnabled is enabled by default. To manually enable SKAdNetwork tracking for your app, turn on the skAdNetworkEnabled configuration option before initializing Singular:

Example:

SingularConfig config = new SingularConfig('API_KEY', 'API_SECRET');
config.skAdNetworkEnabled = true;
config.manualSkanConversionManagement = true; // Enable manual conversion value updates
config.conversionValueUpdatedCallback = (int conversionValue) {
     print('Received conversionValueUpdatedCallback: ' + conversionValue.toString());
};
Singular.init(config);

Retrieving the Conversion Value

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

Send Singular the APNS/FCM token in order to let it track app uninstalls.

Example:

//iOS
  Singular.registerDeviceTokenForUninstall(apnsToken);

//Android
  Singular.registerDeviceTokenForUninstall(fcmToken);

Developing this plugin

Clone the repository into a directory named singular_flutter_sdk:

git clone git@github.com:singular-labs/Singular-Flutter-SDK.git singular_flutter_sdk

The directory name matters. Flutter passes the plugin to Swift Package Manager using the name of the directory it lives in, and Swift Package Manager requires that name to match the pub package name. Cloning into the repository's default directory name (Singular-Flutter-SDK) makes example/ fail to build with:

unable to override package 'singular_flutter_sdk' because its identity
'singular-flutter-sdk' doesn't match override's identity (directory name)
'singular_flutter_sdk'

This affects only this repository's own example/ app. Apps that depend on the published package are unaffected, since pub resolves it into a correctly named directory.

When bumping the native iOS SDK, update the version in both ios/singular_flutter_sdk.podspec and ios/singular_flutter_sdk/Package.swift.