Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add Web Setup Guide to Auto-Instrumentation Docs #7042

Merged
merged 5 commits into from
Oct 1, 2024
Merged

Add Web Setup Guide to Auto-Instrumentation Docs #7042

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6463153
add web setup guide to auto-inst [netlify-build]
alanjcharles Sep 17, 2024
0854956
add config options to each setup guide [netlify-build]
alanjcharles Sep 17, 2024
d843715
fix some typos
pwseg Oct 1, 2024
7889e89
add redirect
pwseg Oct 1, 2024
651fa09
Restore Gemfile
pwseg Oct 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 3 additions & 33 deletions src/connections/auto-instrumentation/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,48 +3,18 @@ title: Generate Events from Signals
hidden: true
---

This guide is a reference to configuring, generating, and using signals in the Signals SDK with Auto-Instrumentation. On this page, you'll find details on:
This guide details how to use signals, and their associated data, generated in one of the Signals SDKs with the Auto-Instrumentation dashboard in your Segment workspace. On this page, you'll find details on:

- Setting up and managing signal types in the Signals SDK
- Creating custom rules to capture and translate signals into actionable analytics events
- Example rules that you can use as a basis for further customization

This guide assumes that you've already added the Signals SDK to your application. If you haven't yet, see the [Auto-Instrumentation Setup](/docs/connections/auto-instrumentation/setup/) guide for initial setup.
This guide assumes that you've already added the Signals SDK to your application. If you haven't yet, see the [Auto-Instrumentation Setup](/docs/connections/auto-instrumentation/) guide for initial setup.

> info "Auto-Instrumentation Pilot"
> Auto-Instrumentation is currently in pilot and is governed by Segment's [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="_blank"}. Segment doesn't recommend Auto-Instrumentation for use in a production environment, as Segment is actively iterating on and improving the user experience.

> success "Enable Auto-Instrumentation"
> To enable Auto-Instrumentation in your Segment workspace, reach out to your dedicated account manager.

## Signals configuration

Using the Signals Configuration object, you can control the destination, frequency, and types of signals that Segment automatically tracks within your application. The following tables detail the configuration options for both Signals-Swift and Signals-Kotlin.

### Signals-Swift

| `Option` | Required | Value | Description |
| ---------------------- | -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `writeKey` | Yes | String | Source write key |
| `maximumBufferSize` | No | Integer | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is `1000`. |
| `relayCount` | No | Integer | Relays signals to Segment every Xth event. Default is `20`. |
| `relayInterval` | No | TimeInterval | Relays signals to segment every X seconds. Default is `60`. |
| `broadcasters` | No | `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`. |
| `useUIKitAutoSignal` | No | Bool | Tracks UIKit component interactions automatically. Default is `false`. |
| `useSwiftUIAutoSignal` | No | Bool | Tracks SwiftUI component interactions automatically. Default is `false`. |
| `useNetworkAutoSignal` | No | Bool | Tracks network events automatically. Default is `false`. |
| `allowedNetworkHosts` | No | Array | An array of allowed network hosts. |
| `blockedNetworkHosts` | No | Array | An array of blocked network hosts. |


### Signals-Kotlin

| `Option` | Required | Value | Description |
| ------------------- | -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `writeKey` | Yes | String | Source write key |
| `maximumBufferSize` | No | Integer | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is `1000`. |
| `broadcastInterval` | No | Integer | Broadcasts signals to Segment every X event. Default is `60`. |
| `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`. |
> To enable Auto-Instrumentation in your Segment workspace, reach out to your dedicated account manager.


## Converting signals to events
Expand Down
48 changes: 47 additions & 1 deletion src/connections/auto-instrumentation/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,27 @@
---
title: Auto-Instrumentation
hidden: true
sources:
- name: Android
url: /connections/auto-instrumentation/kotlin-setup/
logo:
url: https://cdn.filepicker.io/api/file/9BoiIqVRFmsAuBbMMy9D
mark:
url: https://cdn.filepicker.io/api/file/9BoiIqVRFmsAuBbMMy9D
- name: Apple
url: /connections/auto-instrumentation/swift-setup/
logo:
url: https://cdn.filepicker.io/api/file/qWgSP5cpS7eeW2voq13u
mark:
url: https://cdn.filepicker.io/api/file/qWgSP5cpS7eeW2voq13u
- name: Web
url: /connections/auto-instrumentation/web-setup/
logo:
url: https://cdn.filepicker.io/api/file/aRgo4XJQZausZxD4gZQq
mark:
url: https://cdn.filepicker.io/api/file/aRgo4XJQZausZxD4gZQq
redirect_from:
- '/docs/connections/auto-instrumentation/setup/'
---

Auto-Instrumentation simplifies tracking in your websites and apps by eliminating the need for a traditional Segment instrumentation.
Expand Down Expand Up @@ -29,10 +50,35 @@ Some Auto-Instrumentation advantages include:

## How it works

After you [integrate the Analytics SDK and Signals SDK into your application](/docs/connections/auto-instrumentation/setup/), Segment begins to passively monitor user activity like button clicks, page navigation, and network data. Segment captures these events as "signals" and sends them to your Auto-Instrumentation source in real time.
Once you integrate the Analytics SDK and Signals SDK into your website or application, Segment begins to passively monitor user activity like button clicks, page navigation, and network data. Segment captures these events as "signals" and sends them to your Auto-Instrumentation source in real time.

In Segment, the Auto-Instrumentation source lets you view raw signals. You can then [use this data to create detailed analytics events](/docs/connections/auto-instrumentation/configuration/) based on those signals, enriching your insights into user behavior and applicatino performance.

## Setup Guides

<div class="auto-instrumentation-catalog">
<div class="auto-insturmentation__section markdown" id="{{ category | slugify }}">
<div class="flex flex--wrap waffle waffle--xlarge">
{% assign category = "source" %}
{% assign resources = page.sources %}
{% for resource in resources %}
<div class="flex__column flex__column--6">
<a class="thumbnail-integration flex flex--middle" href="{{ site.baseurl }}/{{ resource.url }}">
<div class="thumbnail-integration__content">
<div class="flex flex--wrap flex--middle waffle waffle--xlarge@medium">
<div class="flex__column flex__column--12 flex__column--2@medium thumbnail-integration__logo-wrapper">
<img class="thumbnail-integration__logo image" alt="{{resource.name}}" src="{{resource.mark.url}}" />
</div>
<h5 class="flex__column flex__column--12 flex__column--10@medium">{{ resource.name }}</h5>
</div>
</div>
</a>
</div>
{% endfor %}
</div>
</div>
</div>

## Privacy

Auto-Instrumentation removes personally identifiable information (PII) from breadcrumbs before they get sent to Segment. No user data is visible to Segment.
77 changes: 19 additions & 58 deletions ...connections/auto-instrumentation/setup.md → ...ions/auto-instrumentation/kotlin-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Auto-Instrumentation Setup
hidden: true
---

This guide outlines the steps required to set up the Signals SDK in your applications using Swift or Kotlin.
This guide outlines the steps required to set up the Signals SDK in your Android OS applications using Kotlin.

You'll learn how to add Auto-Instrumentation sources, integrate dependencies, and ensure that your setup captures and processes data as intended.

Expand All @@ -25,61 +25,7 @@ You'll first need to add a source and copy its write key:

## Step 2: Add dependencies and initialization code

Next, you'll need to add the Signals SDKs to your Swift and Kotlin development environments.

### Swift

Follow these steps to integrate the Signals SDK into your Swift application:

1. Use Swift Package Manager to add the Signals SDK from the following repository:

```zsh
https://github.com/segmentio/Signals-swift.git
```

2. Add the initialization code:

```swift
// Configure Analytics with your settings
{... <analytics config>....}

// Set up the Signals SDK configuration
let config = Signals.Configuration(
writeKey: "<WRITE_KEY>", // Replace <WRITE_KEY> with the write key you previously copied
maximumBufferSize: 100,
useSwiftUIAutoSignal: true,
useNetworkAutoSignal: true
)

// Locate and set the fallback JavaScript file for edge functions
let fallbackURL = Bundle.main.url(forResource: "MyEdgeFunctions", withExtension: "js")

// Apply the configuration and add the Signals plugin
Signals.shared.useConfiguration(config)
Analytics.main.add(plugin: LivePlugins(fallbackFileURL: fallbackURL))
Analytics.main.add(plugin: Signals.shared)
```

Verify that you replaced `<WRITE_KEY>` with the actual write key you copied in Step 1.

#### SwiftUI projects

If your app is written in SwiftUI, you'll need to add a `TypeAlias.swift` file to your project that captures interaction and navigation Signals, like in this example:

```swift
import Foundation
import Signals

typealias Button = SignalButton
typealias NavigationStack = SignalNavigationStack
typealias NavigationLink = SignalNavigationLink
typealias TextField = SignalTextField
typealias SecureField = SignalSecureField
```

### Kotlin

Follow these steps to integrate the Signals SDK into your Kotlin application:
Next, you'll need to add the Signals SDKs to your Kotlin application.

1. Update your module’s Gradle build file to add the right dependencies:

Expand All @@ -98,7 +44,10 @@ Follow these steps to integrate the Signals SDK into your Kotlin application:
}
```

2. Add the following code to your application to initialize the Signals SDK:
2. Add the initialization code and configuration options:

> success ""
> see [configuration options](#configuration-options) for a complete list.

```kotlin
// Configure Analytics with your settings
Expand Down Expand Up @@ -143,6 +92,18 @@ Next, you'll need to verify signal emission and [create rules](/docs/connections

Segment displays `Rule updated successfully` to verify that it saved your rule.

## Configuration Options

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.

| `Option` | Required | Value | Description |
| ------------------- | -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `writeKey` | Yes | String | Source write key |
| `maximumBufferSize` | No | Integer | The number of signals to be kept for JavaScript inspection. This buffer is first-in, first-out. Default is `1000`. |
| `broadcastInterval` | No | Integer | Broadcasts signals to Segment every X event. Default is `60`. |
| `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`. |


## Next steps

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 examples rules.
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.
Loading
Loading