Skip to content

Commit bdfb653

Browse files
sade-wusisade-wusi
authored
Merge pull request #8144 from segmentio/update-auto-instrumentation-setup-guide
Update auto instrumentation setup guide
2 parents 11238b6 + 48efb81 commit bdfb653

File tree

2 files changed

+415
-183
lines changed

2 files changed

+415
-183
lines changed

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

Lines changed: 157 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -17,167 +17,180 @@ This guide shows how to install and configure the library, as well as how to ena
1717
To use Signals with Android, you need:
1818

1919
- An active Segment workspace with Auto-Instrumentation enabled.
20-
- A Kotlin-based Android project.
2120
- Android Gradle Plugin version 7.0 or later.
2221
- A minimum compile SDK version of 21.
2322

2423
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"}.
2524

26-
Segment recommends testing in a development environment before deploying Signals in production. For more information, see [Debug mode](#step-4-enable-debug-mode).
25+
Segment recommends testing in a development environment before deploying Signals in production. For more information, see [Debug mode](#step-3-enable-debug-mode).
2726

28-
## Step 1: Install dependencies
27+
## Prerequisites
2928

30-
To install Signals, add the following dependencies to your app-level Gradle build file.
29+
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.
3130

3231
```groovy
33-
dependencies {
34-
// Core Analytics Kotlin library
35-
implementation("com.segment.analytics.kotlin:android:1.19.1")
36-
37-
// Live plugin for real-time analytics
38-
implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.1.0")
39-
40-
// Signals core library
41-
implementation("com.segment.analytics.kotlin.signals:core:0.5.0")
42-
43-
// Optional: Jetpack Compose UI tracking
44-
implementation("com.segment.analytics.kotlin.signals:compose:0.5.0")
45-
46-
// Optional: OkHttp3 network request tracking
47-
implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0")
48-
49-
// Optional: Screen and route tracking for Navigation components
50-
implementation("com.segment.analytics.kotlin.signals:navigation:0.5.0")
51-
52-
// Optional: HttpURLConnection tracking
53-
implementation("com.segment.analytics.kotlin.signals:java-net:0.5.0")
54-
}
32+
// analytics kotlin
33+
implementation ("com.segment.analytics.kotlin:android:1.22.0")
34+
// live plugin
35+
implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.3.0")
5536
```
5637

57-
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:
58-
59-
- **Compose**: Tracks user interface events in Jetpack Compose.
60-
- **OkHttp3**: Captures requests sent through OkHttp3 or Retrofit.
61-
- **Navigation**: Tracks route changes when using Jetpack Navigation.
62-
- **JavaNet**: Tracks network activity sent through `HttpURLConnection`.
63-
64-
Only add the plugins you plan to use. You can add or remove them later without reinitializing your source.
65-
66-
## Step 2: Initialize the SDK
67-
68-
After you add dependencies, you need to initialize the Analytics client and configure the Signals plugin.
69-
70-
Start by creating the `Analytics` instance using your source's write key. Then add the Signals plugin and configure its settings separately.
71-
72-
```kotlin
73-
// Create the Analytics instance with your configuration
74-
val analytics = Analytics(Configuration(writeKey = "<WRITE_KEY>"))
75-
76-
// Add the live plugin for real-time event handling
77-
analytics.add(LivePlugins())
38+
## Step 1: Getting started
7839

79-
// Add the Signals plugin
80-
analytics.add(Signals)
81-
82-
// Configure Signals settings
83-
Signals.configuration = Configuration(
84-
maximumBufferSize = 1000, // Number of signals to keep in memory
85-
broadcastInterval = 60, // Send signals every 60 seconds
86-
broadcasters = listOf(WebhookBroadcaster("YOUR_WEBHOOK")), // Optional
87-
debugMode = true // For development use only
88-
)
89-
90-
// Optional: Add the Compose plugin to track UI events and interactions
91-
analytics.add(SignalsComposeTrackingPlugin())
40+
To get started:
41+
1. Add Signals Core:
42+
```groovy
43+
// signal core
44+
implementation ("com.segment.analytics.kotlin.signals:core:1.0.0")
45+
```
46+
2. Initialize Signals. For a complete list, see [configuration options](#configuration-options).
47+
```kotlin
48+
//... <analytics config>....
49+
analytics.add(LivePlugins()) // Make sure LivePlugins is added
50+
analytics.add(Signals) // Add the signals plugin
51+
52+
Signals.configuration = Configuration(
53+
// sendDebugSignalsToSegment will relay events to Segment server. Should only be true for development purposes.
54+
sendDebugSignalsToSegment = true
55+
// obfuscateDebugSignals will obfuscate sensitive data
56+
obfuscateDebugSignals = true
57+
// .. other options
58+
)
59+
```
60+
3. Add proper dependency and plugin as needed to:
61+
* [Capture interactions](#capture-interactions).
62+
* [Capture navigation](#capture-navigation).
63+
* [Capture network](#capture-network).
9264

93-
// Optional: Track screen transitions using Navigation
94-
analytics.add(SignalsActivityTrackingPlugin())
95-
navController.turnOnScreenTracking()
96-
```
65+
## Step 2: Additional setup
9766

98-
When you run this code, keep the following in mind:
67+
### Capture interactions
9968

100-
- You need to replace `<WRITE_KEY>` with the key from your Android Source in Segment.
101-
- `debugMode` sends signals to Segment for use in the Event Builder. Only enable it in development environments.
102-
- If your app doesn't use Jetpack Compose or Navigation, you can skip those plugin lines.
69+
#### Kotlin Compose
10370

104-
For more options, see [Configuration options reference](#configuration-options).
71+
1. Add the dependency to your module’s Gradle build file:
72+
```groovy
73+
implementation ("com.segment.analytics.kotlin.signals:compose:1.0.0")
74+
```
10575
106-
## Step 3: Track network requests
76+
2. Add `SignalsComposeTrackingPlugin` to analytics:
77+
```kotlin
78+
analytics.add(SignalsComposeTrackingPlugin())
79+
```
10780
108-
Signals supports automatic tracking of network activity for apps that use OkHttp3, Retrofit, or `HttpURLConnection`.
81+
#### Legacy XML UI
10982
110-
Add the relevant plugin based on your network stack.
83+
1. Add the uitoolkit Gradle Plugin dependency to project-level `build.gradle`:
84+
```groovy
85+
buildscript {
86+
dependencies {
87+
classpath 'com.segment.analytics.kotlin.signals:uitoolkit-gradle-plugin:1.0.0'
88+
}
89+
}
90+
```
91+
2. Apply the plugin in your app-level `build.gradle` and add the dependency:
92+
```groovy
93+
plugins {
94+
// ...other plugins
95+
id 'com.segment.analytics.kotlin.signals.uitoolkit-tracking'
96+
}
97+
98+
dependencies {
99+
// ..other dependencies
100+
implementation ("com.segment.analytics.kotlin.signals:uitoolkit:1.0.0")
101+
}
102+
```
111103
112-
### OkHttp3
113104
114-
1. Add the dependency to your Gradle file:
105+
### Capture navigation
115106
107+
1. Add the navigation Gradle Plugin dependency to project-level `build.gradle`:
116108
```groovy
117-
implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0")
109+
buildscript {
110+
dependencies {
111+
classpath 'com.segment.analytics.kotlin.signals:navigation-gradle-plugin:1.0.0'
112+
}
113+
}
118114
```
119-
120-
2. Add the tracking plugin to your `OkHttpClient`:
121-
115+
2. Apply the plugin in your app-level `build.gradle` and add the dependency:
116+
```groovy
117+
plugins {
118+
// ...other plugins
119+
id 'com.segment.analytics.kotlin.signals.navigation-tracking'
120+
}
121+
122+
dependencies {
123+
// ..other dependencies
124+
implementation ("com.segment.analytics.kotlin.signals:navigation:1.0.0")
125+
}
126+
```
127+
3. (**Optional**): Add `SignalsActivityTrackingPlugin` to analytics to track Activity/Fragment navigation. **This is not required for Compose Navigation**.
122128
```kotlin
123-
val okHttpClient = OkHttpClient.Builder()
124-
.addInterceptor(SignalsOkHttp3TrackingPlugin())
125-
.build()
129+
analytics.add(SignalsActivityTrackingPlugin())
126130
```
127131
128-
### Retrofit
129-
130-
Retrofit is built on top of OkHttp, so the setup is similar.
131-
132-
1. Add the same OkHttp3 plugin shown in the previous sectiion:
132+
### Capture network
133133
134+
#### OkHttp
135+
136+
1. Add the dependency:
134137
```groovy
135-
implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0")
138+
implementation ("com.segment.analytics.kotlin.signals:okhttp3:1.0.0")
136139
```
137140
138-
2. Attach the plugin through your Retrofit client configuration:
139-
141+
2. Add `SignalsOkHttp3TrackingPlugin` as an interceptor to your OkHttpClient:
140142
```kotlin
141-
val okHttpClient = OkHttpClient.Builder()
142-
.addInterceptor(SignalsOkHttp3TrackingPlugin())
143-
.build()
144-
145-
val retrofit = Retrofit.Builder()
146-
.client(okHttpClient)
147-
.baseUrl("https://your.api.endpoint")
148-
.build()
143+
private val okHttpClient = OkHttpClient.Builder()
144+
.addInterceptor(SignalsOkHttp3TrackingPlugin())
145+
.build()
149146
```
150147
151-
### HttpURLConnection
152-
153-
1. Add the JavaNet plugin dependency:
148+
#### Retrofit
154149
150+
1. Add the dependency:
155151
```groovy
156-
implementation("com.segment.analytics.kotlin.signals:java-net:0.5.0")
152+
implementation ("com.segment.analytics.kotlin.signals:okhttp3:1.0.0")
157153
```
158154
159-
2. Install the plugin at runtime:
160-
155+
2. Add `SignalsOkHttp3TrackingPlugin` as an interceptor to your Retrofit client:
161156
```kotlin
162-
JavaNetTrackingPlugin.install()
157+
private val okHttpClient = OkHttpClient.Builder()
158+
.addInterceptor(SignalsOkHttp3TrackingPlugin())
159+
.build()
160+
161+
val retrofit = Retrofit.Builder()
162+
.client(okHttpClient)
163+
.build()
163164
```
164165
165-
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.
166+
#### java.net.HttpURLConnection
167+
1. Add the dependency:
168+
```groovy
169+
implementation ("com.segment.analytics.kotlin.signals:java-net:1.0.0")
170+
```
171+
172+
2. Install the `JavaNetTrackingPlugin` on where you initialize analytics:
173+
```kotlin
174+
JavaNetTrackingPlugin.install()
175+
```
176+
166177
167-
## Step 4: Enable debug mode
178+
## Step 3: Enable debug mode
168179
169180
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.
170181
171-
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.
182+
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.
183+
184+
In addition, the SDK obfuscates signals sent to Segment by default. To view the completed data, you need to turn off `obfuscateDebugSignals`.
172185
173186
> warning ""
174-
> Only enable `debugMode` in development environments. Avoid using `debugMode` in production apps.
187+
> Only enable `sendDebugSignalsToSegment` in development environments. Avoid using `sendDebugSignalsToSegment` in production apps.
175188
176-
You can enable `debugMode` in one of two ways.
189+
You can enable `sendDebugSignalsToSegment` and turn off `obfuscateDebugSignals` in one of two ways.
177190
178191
### Option 1: Use build flavors
179192
180-
Configure `debugMode` at build time using [Android product flavors](https://developer.android.com/build/build-variants#product-flavors){:target="_blank"}.
193+
Configure `sendDebugSignalsToSegment` and `obfuscateDebugSignals` at build time using [Android product flavors](https://developer.android.com/build/build-variants#product-flavors){:target="_blank"}.
181194
182195
1. In your `build.gradle` file, define two flavors:
183196
@@ -186,10 +199,12 @@ Configure `debugMode` at build time using [Android product flavors](https://deve
186199
...
187200
productFlavors {
188201
prod {
189-
buildConfigField "boolean", "DEBUG_MODE", "false"
202+
buildConfigField "boolean", "SEND_DEBUG_SIGNALS_TO_SEGMENT", "false"
203+
buildConfigField "boolean", "OBFUSCATE_DEBUG_SIGNALS", "true"
190204
}
191205
dev {
192-
buildConfigField "boolean", "DEBUG_MODE", "true"
206+
buildConfigField "boolean", "SEND_DEBUG_SIGNALS_TO_SEGMENT", "true"
207+
buildConfigField "boolean", "OBFUSCATE_DEBUG_SIGNALS", "false"
193208
}
194209
}
195210
}
@@ -199,53 +214,65 @@ Configure `debugMode` at build time using [Android product flavors](https://deve
199214
200215
```kotlin
201216
Signals.configuration = Configuration(
202-
...
203-
debugMode = BuildConfig.DEBUG_MODE
217+
// ... other config options
218+
sendDebugSignalsToSegment = BuildConfig.SEND_DEBUG_SIGNALS_TO_SEGMENT
219+
obfuscateDebugSignals = BuildConfig.OBFUSCATE_DEBUG_SIGNALS
204220
)
205221
```
206222
207223
### Option 2: Use a feature flag
208224
209-
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.
225+
If your app uses [Firebase Remote Config](https://firebase.google.com/docs/remote-config){:target="_blank"} or a similar system, you can control `sendDebugSignalsToSegment` and `obfuscateDebugSignals` remotely.
210226
211227
```kotlin
212228
Signals.configuration = Configuration(
213229
...
214-
debugMode = remoteConfig.getBoolean("debug_mode")
230+
sendDebugSignalsToSegment = remoteConfig.getBoolean("sendDebugSignalsToSegment")
231+
obfuscateDebugSignals = remoteConfig.getBoolean("obfuscateDebugSignals")
215232
)
216233
```
217234

235+
## Step 4: Turn on Auto-Instrumentation in your source
236+
237+
Next, return to the source settings to turn on Auto-Instrumentation:
238+
239+
1. Go to **Connections > Sources**.
240+
2. Select the source you used in [Step 1](#step-1-getting-started).
241+
3. From the source's overview tab, go to **Settings > Advanced**.
242+
4. Toggle Auto-Instrumention on.
243+
218244
## Step 5: Verify event collection
219245

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

222248
1. In your Segment workspace, go to **Connections > Sources** and select the Android Source you configured.
223249
2. Open the **Event Builder** tab.
224-
3. Interact with your app on a simulator or test device:
225-
- Navigate between screens.
226-
- Tap buttons and UI elements.
227-
- Trigger network requests.
228-
229-
If `debugMode` is enabled, Signals appear in real time as you interact with the app.
230-
250+
3. Interact with your app on a simulator or test device:
251+
> - Navigate between screens.
252+
> - Tap buttons and UI elements.
253+
> - Trigger network requests.
254+
>
255+
> If `sendDebugSignalsToSegment` is enabled, Signals appear in real time as you interact with the app.
231256
4. In the Event Builder, select a signal and click **Configure event** to define a new event.
232257
5. After you add any event mappings, click **Publish event rules** to save them.
233258

234259
> info "What if I don't see the Event Builder tab?"
235-
> If you don't see the Event Builder tab, confirm that the SDK is installed correctly and make sure `debugMode` is enabled. Verify that Auto-Instrumentation is enabled in **Settings > Advanced**. If you still don't see it, reach out to your CSM.
260+
> If you don't see the Event Builder tab, confirm that the SDK is installed correctly and make sure `sendDebugSignalsToSegment` is enabled. Verify that Auto-Instrumentation is enabled in **Settings > Advanced**. If you still don't see it, reach out to your CSM.
236261
237262
## Configuration options
238263

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

241266
The following table lists the available options:
242267

243-
| Option | Required | Type | Default | Description |
244-
| ------------------- | -------- | ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
245-
| `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. |
246-
| `broadcastInterval` | No | `Int` (seconds) | `60` | The interval, in seconds, at which buffered signals are sent to broadcasters. |
247-
| `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. |
248-
| `debugMode` | No | `Boolean` | `false` | When `true`, relays signals to Segment so they appear in the Event Builder. Only enable this in development environments. |
268+
| OPTION | REQUIRED | VALUE | DESCRIPTION |
269+
|------------------|----------|---------------------------|-------------|
270+
| **maximumBufferSize** | No | Integer | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is **1000**. |
271+
| **relayCount** | No | Integer | Relays every X signals to Segment. Default is **20**. |
272+
| **relayInterval** | No | Integer | Relays signals to Segment every X seconds. Default is **60**. |
273+
| **broadcasters** | No | List<SignalBroadcaster> | An array of broadcasters. These objects forward signal data to their destinations, like **WebhookBroadcaster**, or you could write your own **DebugBroadcaster** that writes logs to the developer console. **SegmentBroadcaster** is always added by the SDK. |
274+
| **sendDebugSignalsToSegment** | No | Boolean | Turns on debug mode and allows the SDK to relay Signals to Segment server. Default is **false**. It should only be set to true for development purposes. |
275+
| **obfuscateDebugSignals** | No | Boolean | Obfuscates signals being relayed to Segment. Default is **true**. |
249276

250277
## Next steps
251278

0 commit comments

Comments
 (0)