Before You Begin: SDK Prerequisites

Follow the steps in Integrating a Singular SDK: Planning and Prerequisites.

These steps are prerequisites for any Singular SDK integration.

Install the SDK

The Singular SDK is available as a plug-in for Flutter. The instructions below show you how to integrate Singular into your Flutter app.

• This article assumes you have a functional Flutter app.
• To initialize the SDK, you need your Singular SDK Key and SDK Secret. You can get them in the Singular platform at "Developer Tools > SDK Integration > SDK Keys".

To add the Singular Flutter plugin to your project:

1. Add the singular_flutter_sdk: ^1.6.2 to your pubspec.yaml file:

   pubspec.yaml

   dependencies:
     flutter:
       sdk: flutter
     singular_flutter_sdk: ^1.6.2

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

   bash

   flutter packages get

Set Up Prerequisites

iOS Prerequisites

To use the Singular Flutter plugin, add the AdServices framework.

1. Add the AdServices Framework to Your iOS Project:

   • Navigate to the ios folder of your Flutter project.
   • Open Runner.xcworkspace in Xcode (use .xcworkspace if you use CocoaPods, otherwise use .xcodeproj).

2. Add the AdServices Framework:

   • In Xcode, select your project's target (e.g., "Runner").
   • Go to the General tab.
   • Scroll to the Frameworks, Libraries, and Embedded Content section.
   • Click the + button.
   • Search for AdServices.framework and add it.
   • Set the framework status to Optional (to ensure compatibility if the framework is unavailable on older iOS versions).

Android Prerequisites

Adding Required Android Permissions & Dependencies

Add these permissions under the <manifest> tag in your AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

To support Samsung Galaxy Store's install referrer add the following:

<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

If you have disabled transitive dependencies for the Singular SDK, add the following to your android/app/build.gradle:

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

Configuration requirements if using Proguard

Configuring ProGuard for Singular SDK in React Native Android

When integrating the Singular Android SDK into your Flutter Android app, you must add specific ProGuard rules to ensure the SDK functions correctly in release builds. ProGuard (or R8, its modern replacement) is used to optimize and obfuscate code. Without proper ProGuard rules, the Singular SDK or its dependencies may be removed or obfuscated, causing runtime issues.

Follow these steps to configure ProGuard for the Singular SDK:

1. Locate the ProGuard Rules File: In your Flutter project, navigate to the android/app/proguard-rules.pro file. This file contains custom ProGuard rules for your app.
2. Add Singular SDK ProGuard Rules: Append the following lines to android/app/proguard-rules.pro to preserve the Singular SDK and its dependencies:

# Preserve Singular SDK classes
-keep class com.singular.sdk.** { *; }

# Preserve Android Install Referrer library
-keep public class com.android.installreferrer.** { *; }

# Uncomment the following line if you are using the Singular 'revenue' function with Google Play Billing Library
#-keep public class com.android.billingclient.** { *; }

Integrate the SDK

The 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.

Importing the Singular Library

In your main.dart file, add the following code to import the Singular classes.

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

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 (ie. main.dart) - 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.

1. Create a SingularConfig object. The object contains your SDK Key and SDK Secret (obtain the Key and Secret by logging into your Singular account and navigating to "Developer Tools > SDK Integration > SDK Keys").

2. Optionally, add multiple configuration methods to set or enable various SDK features.

3. Then, use the start method to initialize the SDK, passing the SingularConfig object.
4. Update your _MyHomePageState class in main.dart to include the initialization code.

Example of a modified main.dart:

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

//...
class MyHomePage extends StatefulWidget { 
  //...
  }
  
  class _MyHomePageState extends State<MyHomePage> {
    //...
    @override 
    void initState() {
      super.initState();
      //...
      SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');
      
      // Enable Logging for testing
      config.logLevel = 3;
      config.enableLogging = true;
        
      // Set hashed User ID if available
      config.customUserId = "b642b4217b34b1e8d3bd915fc65c4452";
      
      // For iOS (Remove this if you are not displaying an ATT prompt)!
      config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
      
      // To enable SkAdNetwork Support
      config.skAdNetworkEnabled = true;
      
      // To enable META Install Referrer
      config.facebookAppId = "INSERT YOUR FACEBOOK APP ID HERE";
      
      // (optional) Using Singular Global Properties feature to capture 
      // third party identifiers. The respective SDK(s) must be initialized
      // before the Singular SDK. Example of passing the CleverTapID.

      // var cleverTapId = CleverTapPlugin.getCleverTapID();
      // config.withGlobalProperty("CLEVERTAPID", cleverTapId, true);

      Singular.start(config);
  }