You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/partners/streams.md
+18-17Lines changed: 18 additions & 17 deletions
Original file line number
Diff line number
Diff line change
@@ -3,52 +3,52 @@ title: Build a Stream
3
3
---
4
4
5
5
> info ""
6
-
> The Developer Center is currently not accepting new components. Segment is committed to redeveloping the Developer Center and a new version will be launched in the future. Include [your information here](https://airtable.com/shrj3BkHMhdeaPYWt){:target="_blank"} and we'll contact you once _Streams_ are made available!
6
+
> The Developer Center is currently not accepting new components. Segment is committed to redeveloping the Developer Center and a new version will be launched in the future. Include [your information here](https://airtable.com/shrj3BkHMhdeaPYWt){:target="_blank"} and we'll contact you once _Streams_ are made available.
7
7
8
8
9
-
Streams enable you to send data to mutual customers from your web services in realtime.
9
+
Streams enable you to send data to mutual customers from your web services in real time.
10
10
11
11
# Building a Stream
12
12
13
-
Segment empowers companies of all sizes to use their customer data to grow their business. In addition to more than 180 analytics and marketing tools that receive data from Segment, there are a growing number of source partners — including Salesforce, Twilio, Stripe, Zendesk, and more — sending data into Segment for their customers to use in any destination. By creating a Segment data stream, you'll enable customers to use data from your tool wherever it's most useful to them.
13
+
Segment empowers companies of all sizes to use their customer data to grow their business. In addition to more than 180 analytics and marketing tools that receive data from Segment, a growing number of source partners — including Salesforce, Twilio, Stripe, Zendesk, and more — send data into Segment for their customers to use in any destination. By creating a Segment data stream, you'll enable customers to use data from your tool wherever it's most useful to them.
14
14
15
15
# Understanding the integration
16
16
17
-
To complete the source set up flow, the customer will need to input the Segment write key for this source in your integrations settings UI. This will enable your tool to route customer data back to Segment correctly.
17
+
To complete the source setup flow, the customer will need to input the Segment write key for this source in your integrations settings UI. This will enable your tool to route customer data back to Segment correctly.
18
18
19
19
Customers can find their write key in the source settings and regenerate it as needed.
20
20
21
21
22
22
23
23
> warning ""
24
-
> Segment working on an OAuth solution to reduce friction for customers. Partner Streams submitted through the developer center *will* be required to support this OAuth as it comes available.
24
+
> Segment is working on an OAuth solution to reduce friction for customers. Partner Streams submitted through the developer center *will* be required to support this OAuth as it comes available.
25
25
26
26
## The Segment Spec
27
27
28
-
To learn about the semantics of the five supported API calls, and the semantic event names and properties Segment recognizes, read the Segment [Spec](/docs/connections/spec).
28
+
To learn about the semantics of the five supported API calls, and the semantic event names and properties Segment recognizes, read the [Segment Spec](/docs/connections/spec).
29
29
30
-
The spec is a critical component of preserving semantics between sources and destinations. If you break the spec, you are breaking the promise of Segment, which is grounds for removal from the catalog.
30
+
The Spec is a critical component of preserving semantics between sources and destinations. If you break the Spec, you are breaking the promise of Segment, which is grounds for removal from the catalog.
31
31
32
32
> info ""
33
33
> If any events you send to Segment match, but do not adhere to, existing events from the Segment Spec (for example, sending "Purchase" instead of "Order Completed" or "install" instead of "Application Installed"), Segment will reject your application.
34
34
35
35
36
-
If there is something unique about your tool that requires specific data points that are not included in the spec, [get in touch](https://segment.com/help/contact/){:target="_blank"}.
36
+
If your tool requires specific data points not included in the Spec, [get in touch](https://segment.com/help/contact/){:target="_blank"}.
37
37
38
38
## Sending data
39
39
40
-
To send events to Segment you should post events directly to the [Segment HTTP API](/docs/connections/sources/catalog/libraries/server/http-api/#track). You may use any server-side Segment [library](/docs/connections/sources/catalog/) to do so. The HTTP API has a couple of basic requirements.
40
+
To send events to Segment, you should post events directly to the [Segment HTTP API](/docs/connections/sources/catalog/libraries/server/http-api/#track). You may use any server-side Segment [library](/docs/connections/sources/catalog/) to do so. The HTTP API has a couple of basic requirements.
41
41
42
42
Beyond the Spec, there are a few additional requirements for partner Streams.
43
43
44
44
### `userId`
45
45
46
-
Each call sent to Segment must contain a `userId`. The `userId` is what allows Segment to identify each unique user. This value should be stored by your tool when you receive an event from Segment.
46
+
Each call sent to Segment must contain a `userId`, which allows Segment to identify unique users. This value should be stored by your tool when you receive an event from Segment.
47
47
48
-
For example, you might receive an `identify` call with a `userId` and `traits` about that user. If that user is sent an email and opens that email, you would want to send an `Email Opened` event back to Segment with that same `userId` . The `userId` should be part of the call body as a top-level object.
48
+
For example, you might receive an Identify call with a `userId` and `traits` about that user. If that user is sent an email and opens that email, you would want to send an `Email Opened` event back to Segment with that same `userId` . The `userId` should be part of the call body as a top-level object.
49
49
50
50
> info ""
51
-
> For Customers, it's critical that the `userId` be consistent across all data flowing through Segment — this has significant implications for Segment billing (based on unique Monthly Tracked Users) and usefulness of data in integrations/warehouses. Passing back the `userId` value sent from Segment into your tool should be the default behavior of your track calls. If you're not a destination, make sure that you're using the customer's internal database ID, not your tool's ID.
51
+
> For Customers, it's critical that the `userId` be consistent across all data flowing through Segment — this has significant implications for Segment billing (based on unique Monthly Tracked Users) and usefulness of data in integrations/warehouses. Passing back the `userId` value sent from Segment into your tool should be the default behavior of your Track calls. If you're not a destination, make sure that you're using the customer's internal database ID, not your tool's ID.
52
52
53
53
If you have your own unique identifier you use in your tool, Segment recommends passing that along as a context property in the event for QA purposes. For example:
54
54
@@ -80,19 +80,20 @@ This should be part of the `context` top-level object and will look like:
80
80
81
81
### `writeKey`
82
82
83
-
Each call must contain a `writeKey`. Segment provides this `writeKey` to customers in the settings panel for each of their sources. As mentioned in the set up flow description above, customers will need to save their Segment write key in your UI in order authenticate calls being made by your tool.
83
+
Each call must contain a `writeKey`. Segment provides this `writeKey` to customers in the settings panel for each of their sources. As mentioned in the setup flow description above, customers will need to save their Segment write key in your UI in order to authenticate calls being made by your tool.
84
84
85
85
The write key is required in the header of every call to identify the customer whose data Segment receives. See the [authentication section](/docs/connections/sources/catalog/libraries/server/http-api/#authentication) of the HTTP API docs for more detail. If you do not include a customer write key in the call header, Segment will reject track calls from your tool.
86
86
87
87
**Rate limits and batching**
88
+
88
89
There is no hard rate limit at which point Segment will drop your data. However, to avoid processing delays, Segment asks partners to send requests at a maximum rate of 50 requests per second.
89
90
90
-
If you want to batch requests to the HTTP endpoint, refer to the batching documentation[here](/docs/connections/sources/catalog/libraries/server/http-api/#import). The suggested maximum rate includes any batch requests.
91
+
If you want to batch requests to the HTTP endpoint, refer to the [batching documentation](/docs/connections/sources/catalog/libraries/server/http-api/#import). The suggested maximum rate includes any batch requests.
91
92
92
93
## Regional Segment
93
-
Segment offers customers the option to lead on data residency by providing regional infrastructure in both the Europe and the United States.
94
+
Segment offers customers the option to lead on data residency by providing regional infrastructure in both Europe and the United States.
94
95
95
-
Segment recommends you enable the user to choose which Segment [endpoint](/docs/guides/regional-segment/#server-side-and-project-sources) to send data to for the given writeKey from your system.
96
+
Segment recommends that you let users choose which Segment [endpoint](/docs/guides/regional-segment/#server-side-and-project-sources) to send data to for the given `writeKey` from your system.
96
97
97
98
# Process
98
99
@@ -111,7 +112,7 @@ All three of these steps should be completed before you begin testing:
111
112
112
113
## Testing
113
114
114
-
1. If you don't have a test account up and running already, [create a free Segment account](https://segment.com/signup).
115
+
1. If you don't have a test account up and running already, [create a free Segment account](https://segment.com/signup){:target="_blank"}.
115
116
2. Set up a source depending on the kinds of events you need to test. For example, if your source sends mobile event data, you'll need to instrument a Segment mobile SDK into a demo app.
116
117
3. Copy the Segment write key for this source into your integration settings and save.
117
118
4. Take actions that generate the events your source should be sending. For example, if your source is sending email data to Segment, you should:
0 commit comments