Skip to main content
info

Currently only Android platform is supported.

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.

Installation​

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

SDK setup​

Configure SDK on initState() function 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("your-api-key") and pass your api key as an argument. 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() {
  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("<your-api-key>");
  }

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

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

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

Stopping SDK​

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

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​

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 on device boot​

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();
  }
  // ...
}

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("<your-api-key>");
  }

  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 {

  /// 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.
  /// Pass [apiKey] that you received via dashboard for your app.
  Future<void> start(String apiKey) 

  /// 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() 

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

  /// Sets whether to allow SDK to run in background when app is no longer in focus.
  Future<void> setBackground(bool value) 

  /// Checks whether SDK is allowed to start on device boot.
  Future<bool?> isLaunchOnBoot() 

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

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

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

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