Flutter Honeygain SDK Integration guide

This short guide informs how to integrate Honeygain SDK plugin into your Flutter project.

info

Don't forget to generate your Honeygain SDK API Key and download SDK from Developers dashboard first.

warning

Restriction for Google Play Apps. SDK cannot be integrated into applications distributed via Google Play. Minimum required Android API level is 21 (Android 5.0 / Lollipop). Also for Google Play integration you MUST talk to your account manager or someone from [email protected].

Installation for Android

1. Add hg_sdk folder into your project folder.
2. Add hg_sdk plugin dependency path into your pubspec.yaml dependencies scope.
3. Add hgsdk.aar file dependency to your app's gradle file.

Gradle (Kotlin)

gradle.build.kts

dependencies {
    implementation(files("../../hg_sdk/android/libs/hgsdk.aar"))
}

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  hg_sdk:
    path: hg_sdk/

Exemplary project files structure:

my_flutter_project
├── hg_sdk
├── android
│   └── app
│       ├── src
│       └── build.gradle.kts
├── lib
├── pubspec.yaml
...

Gradle (Groovy)

gradle.build

dependencies {
    implementation files('../../hg_sdk/android/libs/hgsdk.aar')
}

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  hg_sdk:
    path: hg_sdk/

Exemplary project files structure:

my_flutter_project
├── hg_sdk
├── android
│   └── app
│       ├── src
│       └── build.gradle
├── lib
├── pubspec.yaml
...

Installation for iOS

1. Add hg_sdk into your project folder.
2. Add hg_sdk plugin dependency path into your pubspec.yaml dependencies scope.
3. Add HgSdk.xcframework file dependency to your app's .podspec file.

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  hg_sdk:
    path: hg_sdk/

your_project_name.podspec

Pod::Spec.new do |s|
  s.name             = 'your_project_name'
  s.version          = '0.0.1'
  ...
  s.preserve_paths = 'HgSdk.xcframework/**/*'
  s.xcconfig = { 'OTHER_LDFLAGS' => '-framework HgSdk' }
  s.vendored_frameworks = 'HgSdk.xcframework'
end

SDK setup

You need to initialize SDK by calling HgSdk.init(apiKey) function by providing your api key before calling HgSdk.start() function.

You need to get a legal consent from the user before starting SDK (SDK will not start without user consent). The simplest way to do that is to call HgSdk.requestConsent() function.

After consent is provided, you can call HgSdk.start(). When consent screen closes you can check if consent was given in onResume() function using HgSdk.isOptedIn() function.

main.dart

import 'package:flutter/material.dart';
import 'package:hg_sdk/hg_sdk.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  await HgSdk.init("<your-api-key>");
  runApp(const MyApp());
}

// ...

class _MyHomePageState extends State<MyHomePage> {
  late final AppLifecycleListener _listener;

  @override
  void initState() {
    super.initState();
    // SDK configuration goes here
    // ...
    // Start SDK when user accepts consent
    _listener = AppLifecycleListener(onResume: () => { startSdk() });
    requestUserConsent();
  }

  Future<void> startSdk() async {
    bool isOptedIn = await HgSdk.isOptedIn() ?? false;
    if (isOptedIn) HgSdk.start();
  }

  @override
  void dispose() {
    _listener.dispose();
    super.dispose();
  }

  Future<void> requestUserConsentOrStart() async {
    bool isOptedIn = await HgSdk.isOptedIn() ?? false;
    if (!isOptedIn) {
      HgSdk.requestConsent();
    } else {
      HgSdk.start();
    }
  }

  @override
  Widget build(BuildContext context) {
    // ...
  }
}

Stopping SDK

Call HgSdk.stop() in order to stop SDK.

Withdraw the consent

User should be able to opt out from using SDK at any time. When user does so within your app, you should call HgSdk.optOut() function, which will immediately stop SDK and will no longer start it unless user grants consent again.

Running in background (Android)

warning

In most cases if HgSdk.isBackground() is set to false (default) SDK will only run for a short while after your application is closed, because Android system will shut it down as well.

If you want to keep SDK running in background when app is closed, you need to take some additional steps. A few additional FOREGROUND_SERVICE permission are required. Add them to your AndroidManifest.xml

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- Permissions for background functionality -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />

    <application ...
    </application>
</manifest>

Then let SDK know that you want to allow it to run in the background.

main.dart

// ...
class _MyHomePageState extends State<MyHomePage> {
  // ...
  @override
  void initState() {
    super.initState();
    // SDK configuration goes here
    HgSdk.setBackground(true);
    // (optional) Notification customization
    HgSdk.setNotification(NotificationDetails(title: "MyTitle", body: "MyBody", icon: "drawable_in_android_project")
    HgSdk.setNotificationId(42)

    // Start SDK when user accepts consent
    _listener = AppLifecycleListener(onResume: () => { startSdk() });
    requestUserConsent();
  }
  // ...
}

Running in background (iOS)

Depending on your application's use case, you can enable Location updates or Audio, AirPlay and Picture in Picture background modes, so that your application and the SDK would be performant while in background.

• To enable background mode for the Location updates use-case:

  • In your application target settings select -> Signing & Capabilities -> + Capability -> Background Modes;
  • In the Background Modes section, select Location updates and Background processing checkboxes.

• To enable background mode for Audio, AirPlay and Picture in Picture use case:

  • In your application target settings select -> Signing & Capabilities -> + Capability -> Background Modes;
  • In the Background Modes section, select Audio, AirPlay and Picture in Picture and Background processing checkboxes.

warning

Logic for audio playback or location updates usage has to be implemented by application's developer for extended runtime in background mode to be allocated by the iOS.

Running on device boot (Android)

In order to start SDK on device startup, set HgSdk.isLaunchOnBoot() to true. It can be used when you provide long-running service that should have SDK running alongside.

AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- Permissions for on boot functionality -->
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

    <application ...
    </application>
</manifest>

warning

Usually if you set HgSdk.setLaunchOnBoot(true) you should set HgSdk.setBackground(true) as well. Check Running in background section for more information.

main.dart

// ...
class _MyHomePageState extends State<MyHomePage> {
  // ...
  @override
  void initState() {
    super.initState();
    // SDK configuration goes here
    HgSdk.setBackground(true);
    HgSdk.setLaunchOnBoot(true);
    // Start SDK when user accepts consent
    _listener = AppLifecycleListener(onResume: () => { startSdk() });
    requestUserConsent();
  }
  // ...
}

Custom consent window

If default SDK consent window doesn't suit your needs, you can create a custom consent window. Make sure to call HgSdk.optIn() whenever user gives a consent and HgSdk.optOut() whenever user declines it.

warning

Custom consent screen must be approved by our team to maintain clarity for end user.

main.dart

  // ...
  Future<void> requestUserConsent() async {
    bool isOptedIn = await HgSdk.isOptedIn() ?? false;
    if (isOptedIn) return;
    // Show custom consent UI
  }
  
  Future<void> optInAndStart() async {
    await HgSdk.optIn(); // Consent already accepted
    HgSdk.start();
  }

  Future<void> optOut() async {
    await HgSdk.optOut();
  }
  // ...

Logging

You can enable SDK logging to check if SDK is integrated correctly.

main.dart

// ...
class _MyHomePageState extends State<MyHomePage> {
  // ...
  @override
  void initState() {
    super.initState();
    // SDK configuration goes here
    HgSdk.enableLogging(true);
    // Start SDK when user accepts consent
    _listener = AppLifecycleListener(onResume: () => { startSdk() });
    requestUserConsent();
  }
  // ...
}

Exemplary log:

12:13:17.443  I  start: <your-api-key>
12:13:17.445  I  checkAndStart(isConsentGiven = true, isRunning = false)
12:13:17.445  I  Session started 83184d75-eg6e-43a6-bb05-c898c415b8bg
12:13:17.873  I  I'm alive...
12:13:17.887  I  I'm alive..
12:14:13.037  I  I'm alive...
12:14:13.081  I  I'm alive..
12:14:47.867  I  Session is restarting
12:14:47.893  E  Unable to resolve host
12:14:47.896  E  Unable to resolve host
12:14:48.925  I  Session is restarting
12:14:50.218  I  I'm alive...
12:14:50.222  I  I'm alive..
12:14:55.509  I  stop
12:14:55.510  I  Session stopped

SDK API

Full SDK API documentation

main.dart

abstract class HgSdkPlatform extends PlatformInterface {

  /// First function to call for SDK. Prepares SDK for configuration and use.
  /// Pass [apiKey] that you received via dashboard for your app.
  Future<void> init(String apiKey)

  /// Check if current platform is supported
  Future<bool?> isPlatformSupported()

  /// Enable logging with "HgSdk" tag
  Future<void> enableLogging(bool value)

  /// Informs SDK that user gave consent. Used with custom consent requests when
  /// provided consent UI is insufficient.
  /// This does not start SDK, [start] still needs to be called.
  Future<void> optIn()

  /// Withdraws user's consent and stops SDK if it was running.
  Future<void> optOut()

  /// Starts SDK if user has given the consent, otherwise does nothing.
  Future<void> start()

  /// Stops SDK if it's running.
  Future<void> stop() 

  /// Starts an window displaying consent request.
  Future<void> requestConsent()

  /// Checks whether SDK has been started.
  Future<bool?> isRunning() 

  /// Checks whether user has given the consent to start SDK.
  Future<bool?> isOptedIn() 

  /// Only for Android
  /// Checks whether SDK is allowed to run in background when app is no longer in focus.
  Future<bool?> isBackground() 

  /// Only for Android
  /// Sets whether to allow SDK to run in background when app is no longer in focus.
  Future<void> setBackground(bool value) 
  
  /// Only for Android
  /// Checks whether SDK is allowed to start on device boot.
  Future<bool?> isLaunchOnBoot() 

  /// Only for Android
  /// Sets whether to allow SDK to start itself on device boot or not.
  /// Usually used together with [setBackground]
  Future<void> setLaunchOnBoot(bool value)

  /// Only for Android
  /// Sets foreground service notification id
  Future<void> setNotificationId(int value)

  /// Only for Android
  /// Sets custom notification for foreground service
  Future<void> setNotification(NotificationDetails notificationDetails)

}

NotificationDetails

/// Only for Android
class NotificationDetails {
  /// Notification title
  String title;
  /// Notification body text
  String? body;
  /// name of drawable icon for notification
  String icon;
}