Skip to content

Commit feb4c31

Browse files
wenxi-zengwenxi-zeng
committed
update kotlin setup guide
1 parent ac86aba commit feb4c31

File tree

1 file changed

+142
-122
lines changed

1 file changed

+142
-122
lines changed

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

Lines changed: 142 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -25,159 +25,173 @@ Signals supports [Jetpack Compose](https://developer.android.com/compose){:targe
2525

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

28-
## Step 1: Install dependencies
28+
## Prerequisites
2929

30-
To install Signals, add the following dependencies to your app-level Gradle build file.
30+
Auto-Instrumentation (aka 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.
3131

3232
```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-
}
33+
// analytics kotlin
34+
implementation ("com.segment.analytics.kotlin:android:1.22.0")
35+
// live plugin
36+
implementation("com.segment.analytics.kotlin:analytics-kotlin-live:1.3.0")
5537
```
5638

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())
39+
## Step 1: Getting started
7840

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())
41+
Instrumentation becomes as simple as adding dependencies to your module's Gradle file:
42+
1. Add Signals Core
43+
```groovy
44+
// signal core
45+
implementation ("com.segment.analytics.kotlin.signals:core:1.0.0")
46+
```
47+
2. Initialize Signals
48+
```kotlin
49+
//... <analytics config>....
50+
analytics.add(LivePlugins()) // Make sure LivePlugins is added
51+
analytics.add(Signals) // Add the signals plugin
52+
53+
Signals.configuration = Configuration(
54+
// sendDebugSignalsToSegment will relay events to Segment server. Should only be true for development purposes.
55+
sendDebugSignalsToSegment = true
56+
// obfuscateDebugSignals will obfuscate sensitive data
57+
obfuscateDebugSignals = true
58+
// .. other options
59+
)
60+
```
61+
3. Add proper dependency and plugin as needed to:
62+
* [Capture Interactions](#capture-interactions)
63+
* [Capture Navigation](#capture-navigation)
64+
* [Capture Network](#capture-network)
9265
93-
// Optional: Track screen transitions using Navigation
94-
analytics.add(SignalsActivityTrackingPlugin())
95-
navController.turnOnScreenTracking()
96-
```
66+
## Step 2: Additional setup
9767
98-
When you run this code, keep the following in mind:
68+
### Capture Interactions
9969
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.
70+
#### Kotlin Compose
10371
104-
For more options, see [Configuration options reference](#configuration-options).
72+
1. Add the dependency to your module’s Gradle build file.
73+
```groovy
74+
implementation ("com.segment.analytics.kotlin.signals:compose:1.0.0")
75+
```
10576
106-
## Step 3: Track network requests
77+
2. Add `SignalsComposeTrackingPlugin` to analytics
78+
```kotlin
79+
analytics.add(SignalsComposeTrackingPlugin())
80+
```
10781
108-
Signals supports automatic tracking of network activity for apps that use OkHttp3, Retrofit, or `HttpURLConnection`.
82+
#### Legacy XML UI
10983
110-
Add the relevant plugin based on your network stack.
84+
1. Add uitoolkit Gradle Plugin dependency to project level `build.gradle`
85+
```groovy
86+
buildscript {
87+
dependencies {
88+
classpath 'com.segment.analytics.kotlin.signals:uitoolkit-gradle-plugin:1.0.0'
89+
}
90+
}
91+
```
92+
2. Apply the plugin in your app level `build.gradle` and add the dependency
93+
```groovy
94+
plugins {
95+
// ...other plugins
96+
id 'com.segment.analytics.kotlin.signals.uitoolkit-tracking'
97+
}
98+
99+
dependencies {
100+
// ..other dependencies
101+
implementation ("com.segment.analytics.kotlin.signals:uitoolkit:1.0.0")
102+
}
103+
```
111104
112-
### OkHttp3
113105
114-
1. Add the dependency to your Gradle file:
106+
### Capture Navigation
115107
108+
1. Add navigation Gradle Plugin dependency to project level `build.gradle`
116109
```groovy
117-
implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0")
110+
buildscript {
111+
dependencies {
112+
classpath 'com.segment.analytics.kotlin.signals:navigation-gradle-plugin:1.0.0'
113+
}
114+
}
118115
```
119-
120-
2. Add the tracking plugin to your `OkHttpClient`:
121-
116+
2. Apply the plugin in your app level `build.gradle` and add the dependency
117+
```groovy
118+
plugins {
119+
// ...other plugins
120+
id 'com.segment.analytics.kotlin.signals.navigation-tracking'
121+
}
122+
123+
dependencies {
124+
// ..other dependencies
125+
implementation ("com.segment.analytics.kotlin.signals:navigation:1.0.0")
126+
}
127+
```
128+
3. (Optional) Add `SignalsActivityTrackingPlugin` to analytics to track Activity/Fragment navigation. **Not required for Compose Navigation**
122129
```kotlin
123-
val okHttpClient = OkHttpClient.Builder()
124-
.addInterceptor(SignalsOkHttp3TrackingPlugin())
125-
.build()
130+
analytics.add(SignalsActivityTrackingPlugin())
126131
```
127132
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:
133+
### Capture Network
133134
135+
#### OkHttp
136+
137+
1. add dependency:
134138
```groovy
135-
implementation("com.segment.analytics.kotlin.signals:okhttp3:0.5.0")
139+
implementation ("com.segment.analytics.kotlin.signals:okhttp3:1.0.0")
136140
```
137141
138-
2. Attach the plugin through your Retrofit client configuration:
139-
142+
2. add `SignalsOkHttp3TrackingPlugin` as an interceptor to your OkHttpClient:
140143
```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()
144+
private val okHttpClient = OkHttpClient.Builder()
145+
.addInterceptor(SignalsOkHttp3TrackingPlugin())
146+
.build()
149147
```
150148
151-
### HttpURLConnection
152-
153-
1. Add the JavaNet plugin dependency:
149+
#### Retrofit
154150
151+
1. add dependency:
155152
```groovy
156-
implementation("com.segment.analytics.kotlin.signals:java-net:0.5.0")
153+
implementation ("com.segment.analytics.kotlin.signals:okhttp3:1.0.0")
157154
```
158155
159-
2. Install the plugin at runtime:
160-
156+
2. add `SignalsOkHttp3TrackingPlugin` as an interceptor to your Retrofit client:
161157
```kotlin
162-
JavaNetTrackingPlugin.install()
158+
private val okHttpClient = OkHttpClient.Builder()
159+
.addInterceptor(SignalsOkHttp3TrackingPlugin())
160+
.build()
161+
162+
val retrofit = Retrofit.Builder()
163+
.client(okHttpClient)
164+
.build()
163165
```
164166
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.
167+
#### java.net.HttpURLConnection
168+
1. add dependency:
169+
```groovy
170+
implementation ("com.segment.analytics.kotlin.signals:java-net:1.0.0")
171+
```
172+
173+
2. install the `JavaNetTrackingPlugin` on where you initialize analytics:
174+
```kotlin
175+
JavaNetTrackingPlugin.install()
176+
```
166177
167-
## Step 4: Enable debug mode
178+
179+
## Step 3: Enable debug mode
168180
169181
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.
170182
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.
183+
To view captured signals in the Event Builder and create event generation rules, you need to enable `sendDebugSignalsToSegment`. This setting temporarily lets the SDK send signal data to Segment while you're testing.
184+
185+
In addition, the SDK obfuscates signals sent to Segment by default. To view the completed data, you need to turn off `obfuscateDebugSignals`.
172186
173187
> warning ""
174-
> Only enable `debugMode` in development environments. Avoid using `debugMode` in production apps.
188+
> Only enable `sendDebugSignalsToSegment` in development environments. Avoid using `sendDebugSignalsToSegment` in production apps.
175189
176-
You can enable `debugMode` in one of two ways.
190+
You can enable `sendDebugSignalsToSegment` and turn off `obfuscateDebugSignals` in one of two ways.
177191
178192
### Option 1: Use build flavors
179193
180-
Configure `debugMode` at build time using [Android product flavors](https://developer.android.com/build/build-variants#product-flavors){:target="_blank"}.
194+
Configure `sendDebugSignalsToSegment` and `obfuscateDebugSignals` at build time using [Android product flavors](https://developer.android.com/build/build-variants#product-flavors){:target="_blank"}.
181195
182196
1. In your `build.gradle` file, define two flavors:
183197
@@ -186,10 +200,12 @@ Configure `debugMode` at build time using [Android product flavors](https://deve
186200
...
187201
productFlavors {
188202
prod {
189-
buildConfigField "boolean", "DEBUG_MODE", "false"
203+
buildConfigField "boolean", "SEND_DEBUG_SIGNALS_TO_SEGMENT", "false"
204+
buildConfigField "boolean", "OBFUSCATE_DEBUG_SIGNALS", "true"
190205
}
191206
dev {
192-
buildConfigField "boolean", "DEBUG_MODE", "true"
207+
buildConfigField "boolean", "SEND_DEBUG_SIGNALS_TO_SEGMENT", "true"
208+
buildConfigField "boolean", "OBFUSCATE_DEBUG_SIGNALS", "false"
193209
}
194210
}
195211
}
@@ -199,19 +215,21 @@ Configure `debugMode` at build time using [Android product flavors](https://deve
199215
200216
```kotlin
201217
Signals.configuration = Configuration(
202-
...
203-
debugMode = BuildConfig.DEBUG_MODE
218+
// ... other config options
219+
sendDebugSignalsToSegment = BuildConfig.SEND_DEBUG_SIGNALS_TO_SEGMENT
220+
obfuscateDebugSignals = BuildConfig.OBFUSCATE_DEBUG_SIGNALS
204221
)
205222
```
206223
207224
### Option 2: Use a feature flag
208225
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.
226+
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.
210227
211228
```kotlin
212229
Signals.configuration = Configuration(
213230
...
214-
debugMode = remoteConfig.getBoolean("debug_mode")
231+
sendDebugSignalsToSegment = remoteConfig.getBoolean("sendDebugSignalsToSegment")
232+
obfuscateDebugSignals = remoteConfig.getBoolean("obfuscateDebugSignals")
215233
)
216234
```
217235

@@ -226,26 +244,28 @@ After you build and run your app, use the [Event Builder](/docs/connections/auto
226244
- Tap buttons and UI elements.
227245
- Trigger network requests.
228246

229-
If `debugMode` is enabled, Signals appear in real time as you interact with the app.
247+
If `sendDebugSignalsToSegment` is enabled, Signals appear in real time as you interact with the app.
230248

231249
4. In the Event Builder, select a signal and click **Configure event** to define a new event.
232250
5. After you add any event mappings, click **Publish event rules** to save them.
233251

234252
> 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.
253+
> 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.
236254
237255
## Configuration options
238256

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

241259
The following table lists the available options:
242260

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. |
261+
| OPTION | REQUIRED | VALUE | DESCRIPTION |
262+
|------------------|----------|---------------------------|-------------|
263+
| **maximumBufferSize** | No | Integer | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is **1000**. |
264+
| **relayCount** | No | Integer | Relays every X signals to Segment. Default is **20**. |
265+
| **relayInterval** | No | Integer | Relays signals to Segment every X seconds. Default is **60**. |
266+
| **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. |
267+
| **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. |
268+
| **obfuscateDebugSignals** | No | Boolean | Obfuscates signals being relayed to Segment. Default is **true**. |
249269

250270
## Next steps
251271

0 commit comments

Comments
 (0)