Skip to content

Commit 5e14da8

Browse files
pwsegpwseg
authored
Merge pull request #7629 from segmentio/android-auto-instrumentation-updates
Update Kotlin Auto-Instrumentation setup guide for Signals SDK `0.5.0`
2 parents 63774fd + 664d64d commit 5e14da8

File tree

1 file changed

+209
-62
lines changed

1 file changed

+209
-62
lines changed

‎src/connections/auto-instrumentation/kotlin-setup.md

Lines changed: 209 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -3,104 +3,251 @@ title: Auto-Instrumentation Setup
33
hidden: true
44
---
55

6-
This guide outlines the steps required to set up the Signals SDK in your Android OS applications using Kotlin.
6+
Segment’s Signals library powers [Auto-Instrumentation](/docs/connections/auto-instrumentation/) in Android apps, capturing user interactions and behavior without manual event tracking.
77

8-
You'll learn how to add Auto-Instrumentation sources, integrate dependencies, and ensure that your setup captures and processes data as intended.
8+
This guide shows how to install and configure the library, as well as how to enable optional plugins for screen views, network activity, and more.
99

1010
> info "Auto-Instrumentation Private Beta"
1111
> Auto-Instrumentation is currently in Private Beta and is governed by Segment's [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="_blank"}. Segment is actively iterating on and improving the Auto-Instrumentation user experience.
1212
1313
> success "Enable Auto-Instrumentation"
1414
> To enable Auto-Instrumentation in your Segment workspace, reach out to your dedicated account manager.
1515
16-
## Step 1: Add a source and get its write key
16+
## Before you begin
1717

18-
You'll first need to add a source and copy its write key:
18+
To use Signals with Android, you need:
1919

20-
1. In your Segment workspace, navigate to **Connections > Auto-Instrumentation** and click **Add source**.
21-
2. Select a source, give the source a name, and click **Save**.
22-
3. Return to **Connections > Sources** to view your sources.
23-
4. In the **My sources** table, find and click the new source you just set up.
24-
5. In the **Initialize the Client** section, look for and copy the `writeKey` displayed in the code block.
20+
- An active Segment workspace with Auto-Instrumentation enabled
21+
- A Kotlin-based Android project
22+
- Android Gradle Plugin version 7.0 or later
23+
- A minimum compile SDK version of 21
2524

26-
## Step 2: Add dependencies and initialization code
25+
Signals supports [Jetpack Compose](https://developer.android.com/compose){:target="_blank"} and traditional Android UI frameworks. It also includes optional plugins for network tracking using [OkHttp3](https://square.github.io/okhttp/){:target="_blank"}, [Retrofit](https://square.github.io/retrofit/){:target="_blank"}, or `HttpURLConnection`](https://developer.android.com/reference/java/net/HttpURLConnection){:target="_blank"}.
2726

28-
Next, you'll need to add the Signals SDKs to your Kotlin application.
27+
Segment recommends testing in a development environment before deploying Signals in production. For more information, see [Debug mode](#step-4-enable-debug-mode).
2928

30-
1. Update your module’s Gradle build file to add the right dependencies:
29+
## Step 1: Install dependencies
3130

32-
```kotlin
33-
dependencies {
34-
// Add the Analytics Kotlin library
35-
implementation("com.segment.analytics.kotlin:android:1.15.0")
36-
// Add a live plugin for real-time data handling
37-
implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.0.0")
38-
// Add the core Signals library
39-
implementation("com.segment.analytics.kotlin.signals:core:0.0.1")
40-
// Compose plugin for Jetpack Compose UI tracking
41-
implementation("com.segment.analytics.kotlin.signals:compose:0.0.1")
42-
// OkHttp3 plugin for network activity tracking
43-
implementation("com.segment.analytics.kotlin.signals:okhttp3:0.0.1")
44-
}
45-
```
31+
To install Signals, add the following dependencies to your app-level Gradle build file.
32+
33+
```groovy
34+
dependencies {
35+
// Core Analytics Kotlin library
36+
implementation("com.segment.analytics.kotlin:android:1.19.1")
37+
38+
// Live plugin for real-time analytics
39+
implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.1.0")
40+
41+
// Signals core library
42+
implementation("com.segment.analytics.kotlin.signals:core:0.5.0")
43+
44+
// Optional: Jetpack Compose UI tracking
45+
implementation("com.segment.analytics.kotlin.signals:compose:0.5.0")
46+
47+
// Optional: OkHttp3 network request tracking
48+
implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0")
49+
50+
// Optional: Screen and route tracking for Navigation components
51+
implementation("com.segment.analytics.kotlin.signals:navigation:0.5.0")
52+
53+
// Optional: HttpURLConnection tracking
54+
implementation("com.segment.analytics.kotlin.signals:java-net:0.5.0")
55+
}
56+
```
57+
58+
The core libraries are required to enable Signals and real-time analytics. Use the following optional plugins to track additional activity based on your app's architecture:
59+
60+
- **Compose**: Tracks user interface events in Jetpack Compose.
61+
- **OkHttp3**: Captures requests sent through OkHttp3 or Retrofit.
62+
- **Navigation**: Tracks route changes when using Jetpack Navigation.
63+
- **JavaNet**: Tracks network activity sent through `HttpURLConnection`.
64+
65+
Only add the plugins you plan to use. You can add or remove them later without reinitializing your source.
66+
67+
## Step 2: Initialize the SDK
68+
69+
After you add dependencies, you'll need to initialize the Analytics client and configure the Signals plugin.
70+
71+
Start by creating the `Analytics` instance using your source's write key. Then add the Signals plugin and configure its settings separately.
72+
73+
```kotlin
74+
// Create the Analytics instance with your configuration
75+
val analytics = Analytics(Configuration(writeKey = "<WRITE_KEY>"))
76+
77+
// Add the live plugin for real-time event handling
78+
analytics.add(LivePlugins())
4679

47-
2. Add the initialization code and configuration options:
80+
// Add the Signals plugin
81+
analytics.add(Signals)
4882

49-
> success ""
50-
> see [configuration options](#configuration-options) for a complete list.
83+
// Configure Signals settings
84+
Signals.configuration = Configuration(
85+
maximumBufferSize = 1000, // Number of signals to keep in memory
86+
broadcastInterval = 60, // Send signals every 60 seconds
87+
broadcasters = listOf(WebhookBroadcaster("YOUR_WEBHOOK")), // Optional
88+
debugMode = true // For development use only
89+
)
90+
91+
// Optional: Add the Compose plugin to track UI events and interactions
92+
analytics.add(SignalsComposeTrackingPlugin())
93+
94+
// Optional: Track screen transitions using Navigation
95+
analytics.add(SignalsActivityTrackingPlugin())
96+
navController.turnOnScreenTracking()
97+
```
98+
99+
When you run this code, keep the following in mind:
100+
101+
- You'll need to replace <WRITE_KEY> with the key from your Android Source in Segment.
102+
- `debugMode` sends signals to Segment for use in the Event Builder. Only enable it in development environments.
103+
- If your app doesn't use Jetpack Compose or Navigation, you can skip those plugin lines.
104+
105+
For more options, see [Configuration options reference](#configuration-options).
106+
107+
## Step 3: Track network requests
108+
109+
Signals supports automatic tracking of network activity for apps that use OkHttp3, Retrofit, or `HttpURLConnection`.
110+
111+
Add the relevant plugin based on your network stack.
112+
113+
### OkHttp3
114+
115+
1. Add the dependency to your Gradle file:
116+
117+
```groovy
118+
implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0")
119+
```
120+
121+
2. Add the tracking plugin to your `OkHttpClient`:
51122
52123
```kotlin
53-
// Configure Analytics with your settings
54-
{... <analytics config>....}
124+
val okHttpClient = OkHttpClient.Builder()
125+
.addInterceptor(SignalsOkHttp3TrackingPlugin())
126+
.build()
127+
```
55128
56-
// Add live plugins for real-time analytics
57-
analytics.add(LivePlugins())
129+
### Retrofit
58130
59-
// Configure and add the Signals plugin
60-
Signals.configuration = Configuration(
61-
writeKey = "<WRITE_KEY>", // Replace <WRITE_KEY> with the write key you previously copied
62-
maximumBufferSize = 1000,
63-
broadcasters = listOf(SegmentBroadcaster(analytics))
64-
)
131+
Retrofit is built on top of OkHttp, so the setup is similar.
132+
133+
1. Add the same OkHttp3 plugin shown in the previous sectiion:
65134
66-
// Add the Compose plugin for UI events and screen tracking
67-
analytics.add(SignalsComposeTrackingPlugin())
135+
```groovy
136+
implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0")
68137
```
69138
70-
3. (Optional:) If you want to track network activity, configure your OkHttpClient to use the Signals OkHttp3 plugin:
139+
2. Attach the plugin through your Retrofit client configuration:
71140
72141
```kotlin
73-
private val okHttpClient = OkHttpClient.Builder()
142+
val okHttpClient = OkHttpClient.Builder()
74143
.addInterceptor(SignalsOkHttp3TrackingPlugin())
75144
.build()
145+
146+
val retrofit = Retrofit.Builder()
147+
.client(okHttpClient)
148+
.baseUrl("https://your.api.endpoint")
149+
.build()
150+
```
151+
152+
### HttpURLConnection
153+
154+
1. Add the JavaNet plugin dependency:
155+
156+
```groovy
157+
implementation("com.segment.analytics.kotlin.signals:java-net:0.5.0")
158+
```
159+
160+
2. Install the plugin at runtime:
161+
162+
```kotlin
163+
JavaNetTrackingPlugin.install()
76164
```
77165
78-
4. Build and run your app.
166+
Depending on your app’s network stack, you may only need one plugin. If your app uses multiple clients, you can install more than one plugin.
167+
168+
## Step 4: Enable debug mode
169+
170+
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.
171+
172+
To view captured signals in the Event Builder and create event generation rules, you need to enable `debugMode`. This setting temporarily lets the SDK send signal data to Segment while you're testing.
173+
174+
> warning ""
175+
> Only enable `debugMode` in development environments. Avoid using `debugMode` in production apps.
176+
177+
You can enable `debugMode` in one of two ways.
178+
179+
### Option 1: Use build flavors
180+
181+
Configure `debugMode` at build time using [Android product flavors](https://developer.android.com/build/build-variants#product-flavors){:target="_blank"}.
182+
183+
1. In your `build.gradle` file, define two flavors:
184+
185+
```groovy
186+
android {
187+
...
188+
productFlavors {
189+
prod {
190+
buildConfigField "boolean", "DEBUG_MODE", "false"
191+
}
192+
dev {
193+
buildConfigField "boolean", "DEBUG_MODE", "true"
194+
}
195+
}
196+
}
197+
```
198+
199+
2. Update the Signals configuration to use the flag:
200+
201+
```kotlin
202+
Signals.configuration = Configuration(
203+
...
204+
debugMode = BuildConfig.DEBUG_MODE
205+
)
206+
```
207+
208+
### Option 2: Use a feature flag
209+
210+
If your app uses [Firebase Remote Config](https://firebase.google.com/docs/remote-config){:target="_blank"} or a similar system, you can control `debugMode` remotely.
211+
212+
```kotlin
213+
Signals.configuration = Configuration(
214+
...
215+
debugMode = remoteConfig.getBoolean("debug_mode")
216+
)
217+
```
218+
219+
## Step 5: Verify event collection
220+
221+
After you build and run your app, use the [Event Builder](/docs/connections/auto-instrumentation/event-builder/) to confirm that Signals are being collected correctly.
222+
223+
1. In your Segment workspace, go to **Connections > Sources** and select the Android Source you configured.
224+
2. Open the **Event Builder** tab.
225+
3. Interact with your app on a simulator or test device:
226+
- Navigate between screens.
227+
- Tap buttons and UI elements.
228+
- Trigger network requests.
79229

80-
## Step 3: Verify and deploy events
230+
If `debugMode` is enabled, Signals appear in real time as you interact with the app.
81231

82-
After integrating the SDK and running your app, verify that Segment is collecting signals:
232+
4. In the Event Builder, select a signal and click **Configure event** to define a new event.
233+
5. After you add any event mappings, click **Publish event rules** to save them.
83234

84-
1. In your Segment workspace, go to **Connections > Sources** and select the source you created for Auto-Instrumentation.
85-
2. In the source overview, look for the **Event Builder** tab. If the tab doesn’t appear:
86-
- Make sure you've installed the SDK correctly.
87-
- Reach out to your Segment CSM to confirm that your workspace has the necessary feature flags enabled.
88-
3. Launch your app [in debug mode](https://github.com/segmentio/analytics-next/tree/master/packages/signals/signals#sending-and-viewing-signals-on-segmentcom-debug-mode){:target="_blank"}, for example, by running the app from Android Studio on a simulator or test device. This enables signal collection so you can see activity in the Event Builder.
89-
4. Use the app as a user would: navigate between screens, tap buttons, trigger network requests. Signals appear in real time as you interact with the app.
90-
5. In the Event Builder, find a signal and click **Configure event** to define a new event. After configuring the event, click **Publish event rules**.
235+
> info "What if I don't see the Event Builder tab?"
236+
> If you don't see the Event Builder tab, confirm that the SDK is installed correctly and make sure `debugMode` is enabled. If you still don't see it, reach out to your CSM to verify that your workspace has Auto-Instrumentation enabled.
91237
92-
## Configuration Options
238+
## Configuration options
93239

94-
Using the Signals Configuration object, you can control the destination, frequency, and types of signals that Segment automatically tracks within your application. The following table details the configuration options for Signals-Kotlin.
240+
Use the `Signals.configuration` object to control how captured signals are stored, relayed, and displayed.
95241

96-
| `Option` | Required | Value | Description |
97-
| ------------------- | -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
98-
| `writeKey` | Yes | String | Source write key |
99-
| `maximumBufferSize` | No | Integer | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is `1000`. |
100-
| `broadcastInterval` | No | Integer | Broadcasts signals to Segment every X event. Default is `60`. |
101-
| `broadcasters` | No | `List<SignalBroadcaster>` | An array of broadcasters. These objects forward signal data to their destinations, like `WebhookBroadcaster` or `DebugBroadcaster` writing to the developer console. Default is `SegmentBroadcaster`. |
242+
The following table lists the available options:
102243

244+
| Option | Required | Type | Default | Description |
245+
| ------------------- | -------- | ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
246+
| `maximumBufferSize` | No | `Int` | `1000` | The number of captured signals to keep in memory before relaying them. Signals get stored in a first-in, first-out buffer. |
247+
| `broadcastInterval` | No | `Int` (seconds) | `60` | The interval, in seconds, at which buffered signals are sent to broadcasters. |
248+
| `broadcasters` | No | `List<SignalBroadcaster>` | N/A | A list of broadcasters that forward signal data to external destinations. `SegmentBroadcaster` is included by default, and you can add others like `WebhookBroadcaster` or a custom implementation. |
249+
| `debugMode` | No | `Boolean` | `false` | When `true`, relays signals to Segment so they appear in the Event Builder. Only enable this in development environments. |
103250

104251
## Next steps
105252

106-
This guide walked you through initial Signals SDK/Auto-Instrumentation setup. Next, read the [Auto-Instrumentation Signals Implementation Guide](/docs/connections/auto-instrumentation/configuration/), which dives deeper into Signals and offers example rules.
253+
After you've confirmed that signals show up in the Event Builder, use the [Generate Events from Signals](/docs/connections/auto-instrumentation/configuration/) guide to configure how signals get translated into analytics events.

0 commit comments

Comments
 (0)