Merge pull request #7580 from segmentio/auto-instrumentation-private-beta

Auto-Instrumentation Private Beta [DOC-1063]

Author: pwseg

src/connections/auto-instrumentation/configuration.md

@@ -26,6 +26,9 @@ After you set up the Signals SDK to capture the signals you want to target, you
 1. In your Segment workspace, go to to **Connections > Auto-Instrumentation** and click on a source. 
 2. Click **Create Rules**.
 
+> info "Where's the Event Builder tab?"
+> The Event Builder tab only appears after you've installed the Auto-Instrumentation snippet in your site or app. If you don’t see the tab, double check your implementation or reach out to your Segment CSM.
+
 ### Using the Rules Editor
 
 The Rules Editor is where you define rules that transform raw signal data into analytics events. In the editor, you write functions that convert signals into events and then call them in the `processSignal()` function. 

src/connections/auto-instrumentation/event-builder.md

@@ -0,0 +1,89 @@
+---
+title: Auto-Instrumentation Event Builder
+hidden: true
+---
+
+The Event Builder provides a no-code way to define analytics events based on signals collected by Auto-Instrumentation. 
+
+You can use it to create Track, Identify, Page, and other event types directly from your Segment workspace.
+
+> info "Auto-Instrumentation Private Beta"
+> 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.
+
+## Access the Event Builder
+
+The Event Builder appears as a tab within each source, next to the Debugger. If you don't see the Event Builder tab, first confirm that you've installed the required Auto-Instrumentation SDK. 
+
+If you've installed the SDK but still don't see the Event Builder tab, reach out to your Segment account manager to verify your workspace is included in the Auto-Instrumentation Private Beta.
+
+![The Event Builder tab shown in the navigation bar between Debugger and Schema in a Segment source](images/event_builder_tab.png)
+
+> info "Event Builder during Private Beta"
+> During Private Beta, both the Event Builder and the legacy Auto-Instrumentation tab appear in the navigation. Segment will remove the legacy tab once all customers have migrated to the Event Builder experience.
+
+## Generate activity
+
+To populate the Event Builder with signals, you first need to open your website or app with a special query parameter that enables signal detection.
+
+1. Visit your site or app in a browser, and add `?segment_signals_debug=true` to the end of the URL.  
+   For example: `https://www.your-website.com?segment_signals_debug=true`.
+2. Interact with your app as a user would: click buttons, navigate between pages or screens, submit forms, and so on.
+3. Return to the Event Builder tab in Segment to view the signals being collected in real time.
+
+
+![Prompt in the Event Builder showing how to start detecting activity by visiting the website with a debug query parameter and interacting with the app](images/detecting_activity.png)
+
+> info "Enable signal detection"
+> Segment only detects signals when you access your site using the `?segment_signals_debug=true` query parameter. If you visit your site without it, signals won't show up in the Event Builder.
+
+Segment collects and displays activity as signals. These signals are grouped into types, like:
+
+- Interaction: clicks, taps, and UI interactions.
+- Navigation: screen changes and page transitions
+- Network: requests and responses
+- `LocalData`, Instrumentation, and `UserDefined`: additional signal types from the SDK.
+
+### How signals relate to events
+
+Segment separates signal collection from event creation. Signals represent raw user interactions, like a button click or screen view. Events, on the other hand, are analytics calls you define based on those signals. This two-step process lets you observe user behavior first, and then decide how and when to turn that behavior into structured analytics events, without needing to modify your code.
+
+Signal detection is active for 24 hours after you generate activity. Detected signals are available in the Event Builder for 72 hours.
+
+## Create an event
+
+You can create events by selecting individual signals or combining multiple signals in sequence.
+
+Follow these steps to create an event:
+
+1. Find the signal you want to use and click **Configure event**.
+2. Add one or more conditions. The order matters; Segment evaluates them in the order you add them.
+   - For example, to track a successful login, first select a **button click** signal, then the **network response** signal.
+3. Select properties from the signal(s) to include in your event.
+4. Map those properties to your targeted Segment event fields.
+5. Name your event. This name will appear in the Debugger and downstream tools.
+6. Click **Publish event rules** to activate the event in your workspace.
+    - You must publish each rule before Segment starts collecting data for the event.
+
+For example, suppose a user taps an "Add to Cart" button. You can define an `Add to Cart` event by combining the button click signal with a network response signal that includes product details. You can then map properties like product name, ID, and price directly from the network response to your event.
+
+Once published, your event rules appear in the **Event Rules** tab of the Event Builder.  From this tab, you can view all of your published rules and delete rules you no longer need.
+
+![The Event Rules tab shown in the Event Builder, showing six custom rules, categorized by event type](images/event_rules.png)
+
+## Choose an event type
+
+When you define an event in the Event Builder, you assign it a type that determines how Segment and your connected destinations process it. These event types (Track, Identify, Page, and Screen) follow the same structure and behavior defined in the [Segment Spec](/docs/connections/spec/).
+
+| Event type | Description                                                                                                 |
+| ---------- | ----------------------------------------------------------------------------------------------------------- |
+| Track      | Custom event tracking. Use this for user actions like `Product Viewed`, `Add to Cart`, or `Signup Started`. |
+| Identify   | User identification. Use this to associate traits (like `email`, `userId`, or `plan`) with a known user.    |
+| Page       | Web page view tracking. Use this to record visits to pages on your website.                                 |
+| Screen     | Mobile screen view tracking. Use this to record views of screens in your mobile app.                        |
+
+For example, to track a login flow, you might define an Identify event that maps traits like `userId` and `email` from a network response signal. To track cart activity, you could define a Track event like `Checkout Started` with properties like cart value, item count, and currency.
+
+Segment uses the event name and any mapped properties to format each event according to the Segment Spec. Events you create in the Event Builder behave the same way as events sent through Segment SDKs or APIs.
+
+> info "Event type behavior in destinations"
+> While Segment handles these event types consistently, downstream tools may treat them differently. For example, Identify events often update user profiles, while Page or Screen events may be handled as pageviews instead of custom events.

src/connections/auto-instrumentation/images/detecting_activity.png

@@ -24,35 +24,36 @@ 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.
+Auto-Instrumentation simplifies tracking in your websites and apps by removing the need for a traditional Segment instrumentation.
 
-> 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 is actively iterating on and improving the Auto-Instrumentation user experience.
+> info "Auto-Instrumentation Private Beta"
+> 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.
 
 > success "Enable Auto-Instrumentation in your workspace"
 > To enable Auto-Instrumentation in your Segment workspace, reach out to your dedicated account manager.
 
 ## Background
 
-Gathering actionable and timely data is crucial to the success of your business. However, collecting this data in real time has historically proven to be challenging. 
-
-As your business needs change, keeping instrumentation up-to-date across all of your digital properties can be time-consuming, often taking weeks or months. This delay can lead to lost insights, frustration for your marketers and developers, and open-ended support of your Segment instrumentation.
+Collecting high-quality analytics data is essential, but traditional tracking setups often fall behind as business needs change. Instrumentation updates can take weeks or months, and these delays reduce visibility and increase the burden on engineering teams.
 
 ## Auto-Instrumentation as a solution
 
 With just a few lines of code, Auto-Instrumentation handles device tracking for you, helping you focus on collecting the data that's essential to your business and letting your marketers and data analysts gather and update data without relying on engineering teams.
 
-Some Auto-Instrumentation advantages include:
+Key Auto-Instrumentation benefits include:
+
+- **No-code event creation**: Use the Event Builder tab to define events based on user activity; no JavaScript required.
+- **Fast iteration**: Update your tracking configuration at any time, without deploying new app versions.
+- **Fewer dependencies**: Reduce the need for engineering support while still maintaining reliable event tracking.
 
-- **JavaScript-based instrumentation logic**: Configure and refine your instrumentation logic entirely within JavaScript, simplifying the development process and reducing dependencies on other environments.
-- **Rapid iteration**: Update your instrumentation logic without the need to constantly release new versions of your mobile app, enabling faster iterations and improvements.
-- **Bypass update delays**: Avoid the typical delays associated with app update cycles and app store approvals. Auto-Instrumentation lets you update your tracking setups or fix errors immediately, ensuring your data collection remains accurate and timely.
+> info "Event Builder during Private Beta"
+> During the Auto-Instrumentation Private Beta, both the Event Builder and the legacy Auto-Instrumentation tab appear in the Segment UI. Segment will remove the legacy tab once all customers have migrated to the Event Builder experience.
 
 ## How it works
 
-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.
+After you install the required SDKs and enable Auto-Instrumentation, Segment detects activity like button clicks, navigation, and network calls. Segment captures these events as signals, which appear in the Event Builder.
 
-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 application performance.
+You can group signals into complete analytics events, assign names, and map custom properties. 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 application performance.
 
 ## Setup Guides
 

src/connections/auto-instrumentation/images/event_builder_tab.png

@@ -79,18 +79,15 @@ Next, you'll need to add the Signals SDKs to your Kotlin application.
 
 ## Step 3: Verify and deploy events
 
-Next, you'll need to verify signal emission and [create rules](/docs/connections/auto-instrumentation/configuration/#example-rule-implementations) to convert those signals into events:
-
-1. In your Segment workspace, return to **Connections > Auto-Instrumentation** and click on the new source you created. 
-2. Verify that signals appear as expected on the dashboard.
-
-    ![Signals successfully appearing in the Segment UI](images/autoinstrumentation_signals.png "Signals successfully appearing in the Segment UI")
-
-3. Click **Create Rules**.
-4. In the Rules Editor, add a rule that converts signal data into an event.
-5. Click **Preview**, then click **Save & Deploy**.
-
-Segment displays `Rule updated successfully` to verify that it saved your rule.
+After integrating the SDK and running your app, verify that Segment is collecting signals:
+
+1. In your Segment workspace, go to **Connections > Sources** and select the source you created for Auto-Instrumentation.
+2. In the source overview, look for the **Event Builder** tab. If the tab doesn’t appear:
+  - Make sure you've installed the SDK correctly.
+  - Reach out to your Segment CSM to confirm that your workspace has the necessary feature flags enabled.
+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.
+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.
+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**.
 
 ## Configuration Options
 

src/connections/auto-instrumentation/images/event_rules.png

@@ -77,18 +77,15 @@ typealias SecureField = SignalSecureField
 ```
 ## Step 3: Verify and deploy events
 
-Next, you'll need to verify signal emission and [create rules](/docs/connections/auto-instrumentation/configuration/#example-rule-implementations) to convert those signals into events:
-
-1. In your Segment workspace, return to **Connections > Auto-Instrumentation** and click on the new source you created. 
-2. Verify that signals appear as expected on the dashboard.
-
-    ![Signals successfully appearing in the Segment UI](images/autoinstrumentation_signals.png "Signals successfully appearing in the Segment UI")
-
-3. Click **Create Rules**.
-4. In the Rules Editor, add a rule that converts signal data into an event.
-5. Click **Preview**, then click **Save & Deploy**.
-
-Segment displays `Rule updated successfully` to verify that it saved your rule.
+After integrating the SDK and running your app, verify that Segment is collecting signals:
+
+1. In your Segment workspace, go to **Connections > Sources** and select the source you created for Auto-Instrumentation.
+2. In the source overview, look for the **Event Builder** tab. If the tab doesn’t appear:
+  - Make sure you've installed the SDK correctly.
+  - Reach out to your Segment CSM to confirm that your workspace has the necessary feature flags enabled.
+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"}. This enables signal collection so you can see activity in the Event Builder.
+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.
+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**.
 
 ## Configuration Options
 

src/connections/auto-instrumentation/index.md

@@ -65,18 +65,18 @@ Verify that you replaced `<WRITE_KEY>` with the actual write key you copied in S
 
 ## Step 3: Verify and deploy events
 
-Next, you'll need to verify signal emission and [create rules](/docs/connections/auto-instrumentation/configuration/#example-rule-implementations) to convert those signals into events:
+After integrating the SDK and running your app, verify that Segment is collecting signals:
+
+1. In your Segment workspace, return to **Connections > Sources**, then select the source you created for Auto-Instrumentation.
+2. In the source overview, look for the **Event Builder** tab. If the tab doesn’t appear:
+  - Make sure you've installed the SDK correctly.
+  - Reach out to your Segment CSM to confirm that your workspace has the necessary feature flags enabled.
+  ![The Event Builder tab shown in the navigation bar between Debugger and Schema in a Segment Source](images/event_builder_tab.png)
+3. Open the **Event Builder** and follow the on-screen instructions to start signal detection.  
+  - To collect signals in the UI, visit your site in a browser using the query string:`?segment_signals_debug=true`
+4. Interact with your app to trigger signals: click buttons, navigate pages, submit forms, and so on. Segment collects and displays these as signals in real time.
+5. From the signals list, click **Configure event** to define a new event based on one or more signals. After configuring the event, click **Publish event rules**.
 
-1. In your Segment workspace, return to **Connections > Auto-Instrumentation** and click on the new source you created. 
-2. Verify that signals appear as expected on the dashboard.
-
-    ![Signals successfully appearing in the Segment UI](images/autoinstrumentation_signals.png "Signals successfully appearing in the Segment UI")
-
-3. Click **Create Rules**.
-4. In the Rules Editor, add a rule that converts signal data into an event.
-5. Click **Preview**, then click **Save & Deploy**.
-
-Segment displays `Rule updated successfully` to verify that it saved your rule.
 
 ### Debugging
 #### Enable debug mode