Skip to main content

Basic Setup

Quick start​

Example apps​

There are example Flutter app inside the example directory. In there you can check how the Adtrace SDK can be integrated.

Add the SDK to your project​

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

dependencies:
  adtrace_sdk_flutter: ^1.5.0

Then navigate to your project in the terminal and run:

flutter packages get
Install

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 Google Play Services​

Since the 1st of August 2014, apps in the Google Play Store must use the Google Advertising ID to uniquely identify devices. To allow the Adtrace SDK to use the Google Advertising ID, you must integrate the Google Play Services. If you haven't done this yet, please add dependency to Google Play Services library by adding following dependency to your dependencies block of app's build.gradle file for Android platform:

implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
tip

The Adtrace SDK is not tied to any specific version of the play-services-ads-identifier part of the Google Play Services library. You can use the latest version of the library, or any other version you need.

Add permissions​

Please add the following permissions, which the Adtrace 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"/>

If you are not targeting the Google Play Store, please also add the following permission:

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

Add permission to gather Google advertising ID​

If you are targeting Android 12 and above (API level 31), you need to add the com.google.android.gms.AD_ID permission to read the device's advertising ID. Add the following line to your AndroidManifest.xml to enable the permission.

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

For more information, see Google's AdvertisingIdClient.Info documentation.

Proguard settings​

If you are using Proguard, add these lines to your Proguard file:

-keep class io.adtrace.sdk.** { *; }
-keep class com.google.android.gms.common.ConnectionResult {
    int SUCCESS;
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
    com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
    java.lang.String getId();
    boolean isLimitAdTrackingEnabled();
}
-keep public class com.android.installreferrer.** { *; }

If you are not publishing your app in the Google Play Store, you can leave just io.adtrace.sdk package rules:

-keep public class io.adtrace.sdk.** { *; }

Install referrer​

In order to correctly attribute an install of your app to its source, Adtrace needs information about the install referrer. This can be obtained by using the Google Play Referrer API or by catching the Google Play Store intent with a broadcast receiver.

tip

The Google Play Referrer API is newly introduced by Google with the express purpose of providing a more reliable and secure way of obtaining install referrer information and to aid attribution providers in the fight against click injection. It is strongly advised that you support this in your application. The Google Play Store intent is a less secure way of obtaining install referrer information. It will continue to exist in parallel with the new Google Play Referrer API temporarily, but it is set to be deprecated in the future.

Google Play Referrer API​

In order to support this in your app, please make sure to add following dependency to your app's build.gradle file for Android platform:

implementation 'com.android.installreferrer:installreferrer:2.2'

Also, make sure that you have paid attention to the Proguard settings chapter and that you have added all the rules mentioned in it, especially the one needed for this feature:

-keep public class com.android.installreferrer.** { *; }

Google Play Store intent​

The Google Play Store INSTALL_REFERRER intent should be captured with a broadcast receiver. If you are not using your own broadcast receiver to receive the INSTALL_REFERRER intent, add the following receiver tag inside the application tag in your AndroidManifest.xml file for Android platform.

<receiver
    android:name="io.adtrace.sdk.AdTraceReferrerReceiver"
    android:permission="android.permission.INSTALL_PACKAGES"
    android:exported="true" >
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

We use this broadcast receiver to retrieve the install referrer and pass it to our backend.

If you are already using a different broadcast receiver for the INSTALL_REFERRER intent, follow the instructions to add the Adtrace broadcast receiver.

Huawei Referrer API​

As of v2.0.2, the Adtrace SDK supports install tracking on Huawei devices with Huawei App Gallery version 10.4 and higher. for more information see how to use oaid native plugin in flutter.

iOS​

Make sure that following iOS frameworks are linked with your iOS app:

  • iAd.framework - in case you are running iAd campaigns
  • AdServices.framework - in case you are running iAd campaigns
  • AdSupport.framework - for reading iOS Advertising ID (IDFA)
  • CoreTelephony.framework - for reading MCC and MNC information
  • StoreKit.framework - for communication with SKAdNetwork framework
  • AppTrackingTransparency.framework - to ask for user's consent to be tracked and obtain status of that consent

All of these frameworks are enabling certain SDK features, but they are not mandatory for SDK to work normally. With this in mind, you can set Status of each one of these frameworks to Optional in your Project Settings → Build Phases → Link Binary With Libraries section.

Basic setup​

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

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

AdTraceConfig config = new AdTraceConfig('{YourAppToken}', AdTraceEnvironment.sandbox);
AdTrace.start(config);

Replace {YourAppToken} with your app token. You can find this in the panel.

Depending on whether you are building your app for testing or for production, you must set environment with one of these values:

AdTraceEnvironment.sandbox;
AdTraceEnvironment.production;
tip

This value should be set to AdTraceEnvironment.sandbox if and only if you or someone else is testing your app. Make sure to set the environment to AdTraceEnvironment.production before you publish the app. Set it back to AdTraceEnvironment.sandbox when you start developing and testing it again.

We use this environment to distinguish between real traffic and test traffic from test devices. It is imperative that you keep this value meaningful at all times!

Session tracking​

warning

Session tracking are essential for the SDK to function properly. The SDK must "start" when the app starts and "pause" when the app pauses to ensure accurate data collection.

Session tracking for iOS platform is supported out of the box, but in order to perform it properly on Android platform, it requires a bit of additional work described in chapter below.

Session tracking in Android​

On Android platform, it is important for you to hook up into app activity lifecycle methods and make a call to AdTrace.onResume() whenever app enters foreground and a call to AdTrace.onPause() whenever app leaves foreground. You can do this globally or per widget (call these method upon each transition from one widget to another). For example:

class AdTraceExampleApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return new MaterialApp(
      title: 'Adtrace Flutter Example App',
      home: new MainScreen(),
    );
  }
}

class MainScreen extends StatefulWidget {
  @override
  State createState() => new MainScreenState();
}

class MainScreenState extends State<MainScreen> with WidgetsBindingObserver {
  @override
  initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    initPlatformState(); // <-- Initialise SDK in here.
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    switch (state) {
      case AppLifecycleState.inactive:
        break;
      case AppLifecycleState.resumed:
        AdTrace.onResume();
        break;
      case AppLifecycleState.paused:
        AdTrace.onPause();
        break;
      case AppLifecycleState.detached:
        break;
      case AppLifecycleState.hidden:
        break;
    }
  }
}

Adtrace 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:

adtraceConfig.logLevel = AdTraceLogLevel.verbose; // enable all logs
adtraceConfig.logLevel = AdTraceLogLevel.debug; // disable verbose logs
adtraceConfig.logLevel = AdTraceLogLevel.info; // disable debug logs (default)
adtraceConfig.logLevel = AdTraceLogLevel.warn; // disable info logs
adtraceConfig.logLevel = AdTraceLogLevel.error; // disable warning logs
adtraceConfig.logLevel = AdTraceLogLevel.suppress; // disable all logs

Build your app​

Build and run your Flutter app. In your Android/iOS log you can check for logs coming from Adtrace SDK. to insure correct integration checkout testing the integration.