Auto-Instrumentation Setup

To use Signals with Android, you need:

• An active Segment workspace with Auto-Instrumentation enabled.
• Android Gradle Plugin version 7.0 or later.
• A minimum compile SDK version of 21.

Signals supports Jetpack Compose and traditional Android UI frameworks. It also includes optional plugins for network tracking using OkHttp3, Retrofit, or HttpURLConnection.

Segment recommends testing in a development environment before deploying Signals in production. For more information, see Debug mode.

Auto-Instrumentation (also known as Signals) works on top of Analytics and Live Plugins. Make sure to add the following dependencies to your module's Gradle file if you don't have them already.

1
// analytics kotlin 
2
implementation ("com.segment.analytics.kotlin:android:1.22.0")
3
// live plugin 
4
implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.3.0")

To get started:

1. Add Signals Core:
   Copy code block

   1
   // signal core   
   2
   implementation ("com.segment.analytics.kotlin.signals:core:1.0.0")

2. Initialize Signals. For a complete list of Signals configuration options, see configuration options.
   Copy code block

   1
   //... <analytics config>....
   2
   analytics.add(LivePlugins()) // Make sure LivePlugins is added
   3
   analytics.add(Signals)  // Add the signals plugin
   4
   
   5
   Signals.configuration = Configuration(
   6
      // sendDebugSignalsToSegment will relay events to Segment server. Should only be true for development purposes.
   7
      sendDebugSignalsToSegment = true
   8
      // obfuscateDebugSignals will obfuscate sensitive data
   9
      obfuscateDebugSignals = true
   10
      // .. other options
   11
   )

3. Add proper dependency and plugin as needed to:
   • Capture interactions
   • Capture navigation
   • Capture network

1. Add the dependency to your module's Gradle build file:
   Copy code block

   implementation ("com.segment.analytics.kotlin.signals:compose:1.0.0")

2. Add SignalsComposeTrackingPlugin to analytics:
   Copy code block

   analytics.add(SignalsComposeTrackingPlugin())

1. Add the uitoolkit Gradle Plugin dependency to project-level build.gradle:
   Copy code block

   1
   buildscript {
   2
       dependencies {
   3
           classpath 'com.segment.analytics.kotlin.signals:uitoolkit-gradle-plugin:1.0.0'
   4
       }
   5
   }

2. Apply the plugin in your app-level build.gradle and add the dependency:
   Copy code block

   1
   plugins {
   2
       // ...other plugins
   3
       id 'com.segment.analytics.kotlin.signals.uitoolkit-tracking'
   4
   }
   5
   
   6
   dependencies {
   7
     // ..other dependencies
   8
     implementation ("com.segment.analytics.kotlin.signals:uitoolkit:1.0.0")
   9
   }

1. Add the navigation Gradle Plugin dependency to project-level build.gradle:
   Copy code block

   1
   buildscript {
   2
       dependencies {
   3
           classpath 'com.segment.analytics.kotlin.signals:navigation-gradle-plugin:1.0.0'
   4
       }
   5
   }

2. Apply the plugin in your app-level build.gradle and add the dependency:
   Copy code block

   1
   plugins {
   2
       // ...other plugins
   3
       id 'com.segment.analytics.kotlin.signals.navigation-tracking'
   4
   }
   5
   
   6
   dependencies {
   7
     // ..other dependencies
   8
     implementation ("com.segment.analytics.kotlin.signals:navigation:1.0.0")
   9
   }

3. (Optional): Add SignalsActivityTrackingPlugin to analytics to track Activity/Fragment navigation. This is not required for Compose Navigation.
   Copy code block

   analytics.add(SignalsActivityTrackingPlugin())

1. Add the dependency:
   Copy code block

   implementation ("com.segment.analytics.kotlin.signals:okhttp3:1.0.0")

2. Add SignalsOkHttp3TrackingPlugin as an interceptor to your OkHttpClient:
   Copy code block

   1
      private val okHttpClient = OkHttpClient.Builder()
   2
          .addInterceptor(SignalsOkHttp3TrackingPlugin())
   3
          .build()

1. Add the dependency:
   Copy code block

   implementation ("com.segment.analytics.kotlin.signals:okhttp3:1.0.0")

2. Add SignalsOkHttp3TrackingPlugin as an interceptor to your Retrofit client:
   Copy code block

   1
      private val okHttpClient = OkHttpClient.Builder()
   2
          .addInterceptor(SignalsOkHttp3TrackingPlugin())
   3
          .build()
   4
      
   5
      val retrofit = Retrofit.Builder()
   6
          .client(okHttpClient)
   7
          .build()

1. Add the dependency:
   Copy code block

   implementation ("com.segment.analytics.kotlin.signals:java-net:1.0.0")

2. Install the JavaNetTrackingPlugin on where you initialize analytics:
   Copy code block

       JavaNetTrackingPlugin.install()

By default, Signals stores captured data on the device and doesn't forward it to Segment. This process prevents unnecessary bandwidth use and helps support privacy compliance requirements.

To view captured signals in the Event Builder and create event generation rules, enable sendDebugSignalsToSegment. This setting temporarily lets the SDK send signal data to Segment while you're testing.

In addition, the SDK obfuscates signals sent to Segment by default. To view the completed data, you need to turn off obfuscateDebugSignals.

You can enable sendDebugSignalsToSegment and turn off obfuscateDebugSignals in one of two ways.

Configure sendDebugSignalsToSegment and obfuscateDebugSignals at build time using Android product flavors.

1. In your build.gradle file, define two flavors:

   Copy code block

   1
   android {
   2
     ...
   3
     productFlavors {
   4
       prod {
   5
         buildConfigField "boolean", "SEND_DEBUG_SIGNALS_TO_SEGMENT", "false"
   6
         buildConfigField "boolean", "OBFUSCATE_DEBUG_SIGNALS", "true"
   7
       }
   8
       dev {
   9
         buildConfigField "boolean", "SEND_DEBUG_SIGNALS_TO_SEGMENT", "true"
   10
         buildConfigField "boolean", "OBFUSCATE_DEBUG_SIGNALS", "false"
   11
       }
   12
     }
   13
   }

2. Update the Signals configuration to use the flag:

   Copy code block

   1
   Signals.configuration = Configuration(
   2
     // ... other config options
   3
     sendDebugSignalsToSegment = BuildConfig.SEND_DEBUG_SIGNALS_TO_SEGMENT
   4
     obfuscateDebugSignals = BuildConfig.OBFUSCATE_DEBUG_SIGNALS
   5
   )

If your app uses Firebase Remote Config or a similar system, you can control sendDebugSignalsToSegment and obfuscateDebugSignals remotely.

1
Signals.configuration = Configuration(
2
  ...
3
  sendDebugSignalsToSegment = remoteConfig.getBoolean("sendDebugSignalsToSegment")
4
  obfuscateDebugSignals = remoteConfig.getBoolean("obfuscateDebugSignals")
5
)

Next, return to the source settings to turn on Auto-Instrumentation:

1. Go to Connections > Sources.
2. Select the source you used in Step 1.
3. From the source's overview tab, go to Settings > Advanced.
4. Toggle Auto-Instrumention on.

After you build and run your app, use the Event Builder to confirm that Signals are being collected correctly.

1. In your Segment workspace, go to Connections > Sources and select the Android Source you configured.

2. Open the Event Builder tab.

3. Interact with your app on a simulator or test device:

   • Navigate between screens.
   • Tap buttons and UI elements.
   • Trigger network requests.

   (success)

   `sendDebugSignalsToSegment`

   If sendDebugSignalsToSegment is enabled, Signals appear in real time as you interact with the app.

4. In the Event Builder, select a signal and click Configure event to define a new event.

5. After you add any event mappings, click Publish event rules to save them.

Use the Signals.configuration object to control how captured signals are stored, relayed, and displayed.

The following table lists the available options:

After you've confirmed that signals show up in the Event Builder, use the Generate Events from Signals guide to configure how signals get translated into analytics events.