Skip to main content

iOS Honeygain SDK Integration guide

This short guide aims to help you in successfully integrating SDK to your project. In this tutorial we are using XCode IDE, but you can integrate using any IDE of your preferences.

info

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

Installation​

  1. Add HgSdkLib.xcframework file into your application target in the target settings -> General -> Frameworks, Libraries and Embedded content -> + -> Add Other... -> Add files -> Select HgSdkLib.xcframework -> Press Open.
  2. Once the HgSdkLib.xcframework is added to the Frameworks, Libraries and Embedded content section, set the Embed option to Embed & Sign.

SDK setup​

Starting SDK​

First, add the HgSdkLib import to the top of your file. Then, initialize the SDK with HgSdk("YOUR_API_KEY") and pass your api key as an argument. After that, 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 requestConsent() method. After consent is provided, you can call start(). When consent screen closes you can check if consent was given in onAppear() function using isOptedIn() value.

ContentView.swift
import SwiftUI
import HgSdkLib

struct ContentView: View {
    private let sdk = HgSdk(apiKey: "YOUR_API_KEY")
    var body: some View {
        NavigationView {
            ...
        }.onAppear {
            Task {
                if await sdk.isOptedIn() {
                    let startResult = await sdk.start()
                } else {
                    await sdk.requestConsent()
                }
            }
        }
    }
}

Stopping SDK​

Call 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 optOut() function, which will immediately stop SDK and will no longer start it unless user grants consent again.

Running in background​

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

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

warning

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

ContentView.swift
import SwiftUI
import HgSdkLib

struct ContentView: View {
    private let sdk = HgSdk(apiKey: "YOUR_API_KEY")
    var body: some View {
        NavigationView {
            ...
            HStack {
                Spacer()
                Button("Agree") {
                    Task {
                        await sdk.optIn()
                        let startResult = await sdk.start()
                    }
                }
                Spacer()
                Button("Decline") {
                    Task {
                        await sdk.optOut()
                    }
                }
                Spacer()
            }
        }.onAppear {
            Task {
                if await sdk.isOptedIn() {
                    let startResult = await sdk.start()
                }
            }
        }
    }
}

Logging​

You can enable logging to debug console.

ConsentView.swift
import SwiftUI
import HgSdkLib

struct ContentView: View {
    private let sdk = HgSdk(apiKey: "YOUR_API_KEY")
    var body: some View {
        NavigationView {
            ...
        }
        .onAppear {
            sdk.enableLogging(true)
            Task {
                if await sdk.isOptedIn() {
                    let startResult = await sdk.start()
                } else {
                    await sdk.requestConsent()
                }
            }
        }
    }
}

Running in App Sandbox (Optional)​

If you do decide to run your application in "App Sandbox", please make sure to enable incoming and outgoing network connections by:

  • In your application target settings selecting -> Signing & Capabilities;
  • In the App Sandbox section, enable Incoming Connections (Server) and Outgoing Connections (Client) checkboxes.

SDK API​

Full SDK API documentation:


/**
 * Initializes the SDK.
 * Pass [apiKey] that you received via dashboard for your app.
 */
 init(apiKey: String)

/**
 * Sets whether to enable logging to debug console
 */
 func enableLogging(_ isLogging: Bool)

/**
 * Checks whether SDK has been started.
 */
func isRunning() -> Bool

/**
 * Checks whether user has given the consent to start SDK.
 */
func isOptedIn() async -> Bool

/**
 * Starts SDK if user has given the consent and returns `true`, otherwise returns `false`.
 */
func start() async -> Bool

/**
 * Stops SDK if it's running.
 */
func stop() async

/**
 * Withdraws user's consent and stops SDK if it was running.
 */
func optOut() async

/**
 * 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.
 */
func optIn() async

/**
 * Opens up a view displaying consent request with default settings.
 * Returns a `Bool` value, indicating user's acceptance response.
 */
func requestConsent() async -> Bool

/*
 * Returns device identifier
 */
func identify() -> String