Sprig Device Mode Integration

Send events to Sprig using RudderStack device mode.

8 minute read

Send your events to Sprig in web and mobile device mode using the native Sprig SDK.

Find the open source code for this integration below:

Add mobile device mode integration

Once you add Sprig as a destination in the RudderStack dashboard, follow these steps to add it to your mobile project depending on your integration platform:

Follow the steps in this section to add Sprig to your Android project using the new Android (Kotlin) SDK:

Maven Central1.0.1

1. Add dependencies

In your module (app-level) Gradle file (usually <project>/<app-module>/build.gradle.kts or <project>/<app-module>/build.gradle), add the following dependencies:

kotlin

dependencies {
    // RudderStack Kotlin SDK
    implementation("com.rudderstack.sdk.kotlin:android:<latest_version>")

    // RudderStack Sprig integration
    implementation("com.rudderstack.integration.kotlin:sprig:<latest_version>")
}

This integration pulls in the Sprig (UserLeap) Android SDK in the version range 2.23.0 to 3.0.0.

2. Intialize the SDK and the integration

Keep a reference to the SprigIntegration instance — it is needed to present the in-app surveys (explained in Step 3):

kotlin

import android.app.Application
import com.rudderstack.integration.kotlin.sprig.SprigIntegration
import com.rudderstack.sdk.kotlin.android.Analytics
import com.rudderstack.sdk.kotlin.android.Configuration

object RudderAnalyticsUtils {

    lateinit var analytics: Analytics
    val sprigIntegration = SprigIntegration()

    fun initialize(application: Application) {
        analytics = Analytics(
            configuration = Configuration(
                writeKey = "<WRITE_KEY>",
                application = application,
                dataPlaneUrl = "<DATA_PLANE_URL>",
            )
        )
        analytics.add(sprigIntegration)
    }
}

Call RudderAnalyticsUtils.initialize(this) from your Application.onCreate():

kotlin

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        RudderAnalyticsUtils.initialize(this)
    }
}

3. Present in-app surveys

Sprig presents in-app surveys on a FragmentActivity instance. For surveys to render, you need to tell the integration which activity is currently in the foreground, from the activity’s lifecycle callbacks:

If no activity is set, the integration falls back to Sprig.track and the survey is not presented — the event is still delivered to Sprig.

kotlin

import android.os.Bundle
import androidx.fragment.app.FragmentActivity
import com.rudderstack.sampleapp.analytics.RudderAnalyticsUtils

class MainActivity : FragmentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }

    override fun onResume() {
        super.onResume()
        RudderAnalyticsUtils.sprigIntegration.setFragmentActivity(this)
    }

    override fun onPause() {
        RudderAnalyticsUtils.sprigIntegration.setFragmentActivity(null)
        super.onPause()
    }
}

Follow the steps in this section to add Sprig to your iOS project using the iOS (Swift) SDK. Note that the integration supports both Swift and Objective-C consumers.

Swift Package Manager1.0.0

1. Add the package

Add the Sprig integration using the Swift Package Manager:

In Xcode, select File > Add Package Dependencies….
Enter the package repository URL:

https://github.com/rudderlabs/integration-swift-sprig

Select the latest version and target. Then, click Add Package.

You can also add the integration to your Package.swift file, as shown:

swift

dependencies: [
    .package(
        url: "https://github.com/rudderlabs/integration-swift-sprig.git",
        .upToNextMajor(from: "<latest_version>")
    )
]

2. Initialize the SDK and the integration

Create a shared AnalyticsManager that owns the Analytics instance and the SprigIntegration. Keep a reference to sprigIntegration — it is needed to present the in-app surveys (explained in Step 3):

swift

import RudderStackAnalytics
import RudderIntegrationSprig

final class AnalyticsManager {

    static let shared = AnalyticsManager()

    private init() {}

    let analytics: Analytics
    let sprigIntegration: SprigIntegration

    func initialize() {
        let configuration = Configuration(
            writeKey: "<WRITE_KEY>",
            dataPlaneUrl: "<DATA_PLANE_URL>"
        )
        analytics = Analytics(configuration: configuration)

        sprigIntegration = SprigIntegration()
        analytics.add(plugin: sprigIntegration)
    }
}

Trigger initialization from your AppDelegate so the SDK is ready before the first view loads:

swift

import UIKit

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        AnalyticsManager.shared.initialize()
        return true
    }
}

3. Present in-app surveys

The Sprig SDK requires a UIViewController to present in-app surveys. Hand the integration the active view controller via setViewController(_:). The most common pattern is set-on-appear/clear-on-disappear:

swift

import UIKit
import RudderIntegrationSprig

class MainViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
    }

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        AnalyticsManager.shared.sprigIntegration.setViewController(self)
    }

    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        AnalyticsManager.shared.sprigIntegration.setViewController(nil)
    }
}

The integration holds the view controller weakly, so the explicit nil clear is optional. If no view controller is set, the integration calls Sprig.track instead of Sprig.trackAndPresent and the event is still delivered.

Follow these steps to add the Sprig integration to your React Native project.

Set up the RudderStack React Native SDK first.
This integration requires:
@rudderstack/rudder-sdk-react-native v3.1.0 and above
React Native v0.74 and above
For iOS, a deployment target of iOS v15.0 and above

Add the RudderStack-Sprig module to your app:

bash

npm install @rudderstack/rudder-integration-sprig-react-native

bash

yarn add @rudderstack/rudder-integration-sprig-react-native

Import the module and add it to your SDK initialization code:

javascript

import rudderClient from "@rudderstack/rudder-sdk-react-native";
import sprig from "@rudderstack/rudder-integration-sprig-react-native";

const config = {
    dataPlaneUrl: "<DATA_PLANE_URL>",
    trackAppLifecycleEvents: true,
    withFactories: [sprig],
};

rudderClient.setup("<WRITE_KEY>", config);

Present in-app surveys

The React Native integration tracks the foreground Activity (Android) and the key window’s root UIViewController (iOS) automatically and forwards it to the Sprig SDK, so Sprig.trackAndPresent is invoked whenever a foreground host is available. No additional code is needed in your React Native components or in the host native code.

If no foreground host is available at the moment an event is tracked (for example, during cold-start before the first screen renders), the integration falls back to Sprig.track and the event is still delivered to Sprig — only the in-app survey UI is skipped for that event.

Add the following under the dependencies section:

groovy

implementation 'com.rudderstack.android.sdk:core:[1.0,2.0)'
implementation 'com.rudderstack.android.integration:sprig:[1.0.0,)'

Change the SDK initialization to the following:

kotlin

// initialize Rudder SDK
val rudderClient: RudderClient =
    RudderClient.getInstance(
        this,
        WRITE_KEY,
        RudderConfig.Builder()
            .withDataPlaneUrl(DATA_PLANE_URL)
            .withFactory(SprigIntegrationFactory.FACTORY)
            .build()
    )

Import the dependencies for Sprig:

kotlin

import com.rudderstack.android.integration.sprig.SprigIntegrationFactory

Pass the FragmentActivity instance as shown:

Sprig requires this step to display the survey. You can also set it as null to clear the values.

kotlin

class MainActivity: AppCompatActivity() {

    override fun onStart() {
        super.onStart()
        // pass the FragmentActivity instance, it is required by Sprig to display the survey.
        SprigIntegrationFactory.FACTORY.setFragmentActivity(this@MainActivity)
    }
}

Add the following line to your Podfile:

ruby

pod 'Rudder-Sprig'

Run the pod install command.
Change the SDK initialization to the following:

swift

let configBuilder = RSConfigBuilder()
    .withDataPlaneUrl(DATA_PLANE_URL)
    .withFactory(RudderSprigFactory.instance)

RSClient.getInstance(WRITE_KEY, config: configBuilder.build())

Import Rudder_Sprig into ViewController:

swift

import Rudder_Sprig

Pass the instance of ViewController to RudderSprigFactory as shown:

Sprig requires this step to display the survey. You can also set it as nil to clear the values.

swift

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
    
        // Do any additional setup after loading the view.
        
        // Pass ViewController instance to RudderSprigFactory. As Sprig SDK requires this to display the survey.
        RudderSprigFactory.instance.setViewController(self)
    }
}

Identify

You can use the identify call to identify a user in Sprig.

A sample identify call is shown:

javascript

rudderanalytics.identify('1hKOmRA4GRlm', {
  firstName: 'Alex',
  lastName: 'Keener',
  email: "alex@example.com"
});

Supported mappings

RudderStack maps the following optional user attributes in the identify events to the corresponding Sprig fields:

RudderStack property	Sprig property
`userId`	`userId`
`context.traits`	`attributes`
`context.traits.email`	`email`

Track

The track call lets you record any user actions along with the associated properties.

A sample track call is shown:

javascript

rudderanalytics.track('Sample Survey', {
  plan: "Annual",
  accountType: "Pro"
});

If you send a track event called Signed Out, then RudderStack automatically maps it to the logoutUser event before sending it to Sprig. Otherwise, it maps the following event/properties to the corresponding Sprig fields:

RudderStack property	Sprig property
`event` Required	`eventName`
`userId`	`userId`
`properties`	`properties`

Sprig expects the event name to be present in the eventName key. Hence, if you send a track event named Product Added, RudderStack maps it to Sprig’s eventName key before sending it across to Sprig.

To display the survey, you must pass the ViewController instance for iOS and the FragmentActivity instance for Android, otherwise the survey won’t be displayed.
If you do not want to display the survey, you can skip setting FragmentActivity or ViewController. RudderStack then forwards the call to the Sprig.track API instead of Sprig.trackAndPresent.

Reset

The reset method resets the previously identified user and related information.

A sample reset call is shown:

kotlin

analytics.reset()

swift

analytics.reset()

java

RudderClient.getInstance()?.reset()

objectivec

RSClient.getInstance().reset()

Logging

Both the Android (Kotlin) and iOS (Swift) SDK integrations forward the Sprig SDK’s internal log messages to the RudderStack logger, so they appear alongside the rest of your SDK output.

Android (Kotlin)

The Sprig Android SDK emits log messages with a severity (DEBUG, INFO, WARNING, ERROR, CRITICAL). The integration forwards each message to the RudderStack logger at the mapped severity, so Sprig output honours the log level you configure on the SDK.

Set the log level in Configuration when you initialize the SDK:

kotlin

import com.rudderstack.sdk.kotlin.android.Configuration
import com.rudderstack.sdk.kotlin.core.internals.logger.Logger

val config = Configuration(
    writeKey = "<WRITE_KEY>",
    dataPlaneUrl = "<DATA_PLANE_URL>",
    logLevel = Logger.LogLevel.VERBOSE,
)

When the log level is Logger.LogLevel.NONE, the integration skips listener registration entirely and no Sprig output is forwarded.

iOS (Swift)

The Sprig iOS SDK emits log messages without a severity (its loggingEvent callback only carries a message string), so the integration forwards every Sprig message at the verbose level.

To see Sprig output, set the RudderStack log level to anything other than .none:

swift

LoggerAnalytics.logLevel = .verbose

When the log level is set to .none, the integration skips listener registration entirely and no Sprig output is forwarded.

Sprig Device Mode Integration

Add mobile device mode integration

1. Add dependencies

2. Intialize the SDK and the integration

3. Present in-app surveys

1. Add the package

2. Initialize the SDK and the integration

3. Present in-app surveys

Present in-app surveys

Identify

Supported mappings

Track

Reset

Logging

Android (Kotlin)

iOS (Swift)

Questions? Let's figure it out together.