diff --git a/.github/Vocab/Docs/accept.txt b/.github/Vocab/Docs/accept.txt index 8a8556f05d..3c96311dba 100644 --- a/.github/Vocab/Docs/accept.txt +++ b/.github/Vocab/Docs/accept.txt @@ -1,9 +1,11 @@ (?:C|c)annonical (?:C|c)onfig +(?:C|c)rypto (?:D|d)eduplicate (?:D|d)eduplication (?:G|g)tag (?:K|k)laviyo +(?:L|l)odash (?:L|l)ookback (?:P|p)ageviews?\b (?:P|p)endo @@ -19,6 +21,7 @@ allowlist Amberflo Appboy Appsflyer +async Blitzllama blocklist boolean @@ -38,6 +41,7 @@ Friendbuy ga gmail Gradle +Heatmapping href html http @@ -82,6 +86,7 @@ utm Vero Vidora viewability +waitlist WebKit Wootric Zendesk \ No newline at end of file diff --git a/src/_includes/content/dev-center-note.md b/src/_includes/content/dev-center-note.md new file mode 100644 index 0000000000..0639e1f05e --- /dev/null +++ b/src/_includes/content/dev-center-note.md @@ -0,0 +1 @@ +

Developer Center no longer accepts new components.

Segment is redeveloping the Developer Center and will launch a new version when complete. To stay up to date, add your contact information [here](https://airtable.com/shrT3b4C7agUEBKVS){:target="_blank"}.

\ No newline at end of file diff --git a/src/partners/index.md b/src/partners/index.md index 42b2a62295..e1f5f2b320 100644 --- a/src/partners/index.md +++ b/src/partners/index.md @@ -2,8 +2,7 @@ title: Developer Center Overview --- -> note "" -> **NOTE:** Developer Center is currently in _Developer Preview_. If you are interested in joining the Developer Preview, request access [here](https://segment.com/partners/developer-center/). The use is governed by [(1) Segment First Access](https://segment.com/legal/first-access-beta-preview/) and Beta Terms and Conditions and [(2) Segment Acceptable Use Policy](https://segment.com/legal/acceptable-use-policy/). By starting or continuing this process, you also agree to the [Segment Platform Partners Agreement](https://segment.com/legal/partnersagreement/). +{% include content/dev-center-note.md %} ## Building on Segment @@ -14,7 +13,7 @@ Below is a sample screenshot of a customer's Segment dashboard, showing all thei ![](images/overview.png) -Segment's core feature is our Connections Catalog: +Segment's core feature is the Connections Catalog: ![](images/catalog.gif) @@ -22,7 +21,7 @@ Customers discover your Sources and Destinations using the Connections Catalog a The development process is simple: -1. Understand Segment's [Conceptual Model](/docs/partners/conceptual-model) and [Spec](https://segment.com/docs/connections/spec). +1. Understand Segment's [Conceptual Model](/docs/partners/conceptual-model) and [Spec](/docs/connections/spec). 2. Follow Segment's security guidance. 3. Request [access to the Segment Developer Center](https://segment.com/partners/developer-center/). 4. Create an App. @@ -37,7 +36,7 @@ It's important to understand Segment's [Conceptual Model](/docs/partners/concept ### 2. Follow Segment's security guidance -Security is a priority for us at Segment for both our customers and our partners. Before you start building on the Developer Center, please review our [Acceptable Use Policy](https://segment.com/legal/acceptable-use-policy/) and ensure you're following the below guidance: +Security for both customers and partners is a priority at Segment. Before you start building on the Developer Center, review the [Acceptable Use Policy](https://segment.com/legal/acceptable-use-policy/) and ensure you're following the below guidance: - Follow a secure software-development lifecycle, which enables you to create code that is safe for Segment customers and their end users, and that enables you to maintain and raise the security of that code over time - If you or your code comes into contact with Segment customer- or end-user data for any reason, protect it with commercially reasonable methods throughout its data lifecycle, including creation, handling, transporting, storing and destruction. @@ -48,14 +47,12 @@ Security is a priority for us at Segment for both our customers and our partners During _Developer Preview_, you will need to [request access to Developer Center](https://segment.com/partners/developer-center/). A Segment account is required for this step. -We receive a large volume of requests so we encourage you to include a valid company website and email address, answer all questions with details about integration's use case as well as highlighting specific customer requests to expedite the approval process. +Segment receives a large volume of requests so please include a valid company website and email address, answer all questions with details about integration's use case as well as highlighting specific customer requests to expedite the approval process. ### 4. Create your App -Once approved, you can create your first [App](/docs/partners/conceptual-model/#apps). This represents a tile in the [Segment catalog](https://segment.com/catalog/) irrespective of which [Component](/docs/partners/conceptual-model/#components) type you choose to build so it should reflect your tool's name (eg. Zendesk Chat, Zendesk Sell). +Once approved, you can create your first [App](/docs/partners/conceptual-model/#apps). This represents a tile in the [Segment catalog](https://segment.com/catalog/) irrespective of which [Component](/docs/partners/conceptual-model/#components) type you choose to build so it should reflect your tool's name (for example, Zendesk Chat, Zendesk Sell). -> info "" -> The Developer Center currently only supports new Partner integrations (ie. Currently does not exist on the [Segment catalog](https://segment.com/catalog/)) in _Developer Preview_. If you're an existing Partner looking to build a new Component or make changes to your existing integration, fill in [your details here](https://airtable.com/shrSweuRx5jspwsw7) and we'll contact you once this is made available! ### 5. Build & Test @@ -65,16 +62,14 @@ Now you can start building! Depending on your use case you can build a: - [Plugin](/docs/partners/plugins) - [Stream](/docs/partners/streams) -> info "" -> The Developer Center currently only supports the [Subscription](/docs/partners/subscriptions) component in _Developer Preview_. If you're looking to build a [Web Plugin](https://airtable.com/shrT3b4C7agUEBKVS) or [Stream](https://airtable.com/shrj3BkHMhdeaPYWt) fill out the respective form and we'll contact you once this is made available! -No matter which Component you decide to build, make it aligns with the [Segment Spec](https://segment.com/docs/connections/spec). This is a critical component in preserving logical continuity between disparate writers and readers of data. If you encourage customers to break the spec, you are breaking the promise of Segment, and is grounds for removal from the catalog. +No matter which Component you decide to build, make it aligns with the [Segment Spec](/docs/connections/spec). This is a critical component in preserving logical continuity between disparate writers and readers of data. If you encourage customers to break the spec, you are breaking the promise of Segment, and is grounds for removal from the catalog. -It's important that we provide a great experience for our mutual customers so we ask that you also conduct thorough testing of your integration using the tooling provided to you through the Developer Center. We also encourage you to use your Segment sandbox in the shoes of a user to polish the experience of implementing and using your integration. +To provide a positive experience for mutual customers, it's important to test integrations with the tooling provided by the Developer Center. You can also use your Segment sandbox to polish the experience your end users will see. ### 6. Document -Finally, make sure you prepare documentation and relevant marketing material for easy discovery and reference. We ask that you provide the following documentation about your integration by making a copy of the below templates: +Finally, make sure you prepare documentation and relevant marketing material for easy discovery and reference. Provide the following documentation about your integration by making a copy of the below templates: 1. Documentation [hosted by Segment](https://segment.com/docs/) for [Subscription / Plugin](https://hackmd.io/t7amLXluS7-39rg7ARZgSA) or [Stream](https://hackmd.io/TV8cZR6tRnKwGtkvSexeag) 2. Documentation for [the Segment catalog](https://segment.com/catalog/) using [this template](https://docs.google.com/document/d/1kKvqYtZeDPnBjvCrtQSuO3BBH70b_CLO13hYrYIOOtA/edit)) @@ -84,9 +79,9 @@ Finally, make sure you prepare documentation and relevant marketing material for ### 7. Submission -You can submit your Component in the Developer Center for review. We strive to respond to your submission within 2 business days to kickstart the review process. +You can submit your Component in the Developer Center for review. Segment aims to respond to your submission within two business days to kickstart the review process. -Our team will test your integration and review your documentation and marketing material. In order to keep this review feedback loop short, make sure that your integration: +Segment tests your integration and reviews your documentation and marketing material. To keep this review feedback loop short, make sure that your integration: - Adheres to the [Segment Spec](/docs/connections/spec/) - Adheres to your published documentation @@ -99,33 +94,32 @@ See the [Public Beta Checklist](/docs/partners/checklist) for a detailed checkli In a nutshell you need: -1. A working integration tested end-to-end. We encourage you to follow your own documentation and run through the experience as one of our mutual customers. +1. A working integration tested end-to-end. Follow your own documentation and run through the experience as a mutual customer. 2. Complete the fields under the _App Info_ tab with your App including both _Basic Info_ and _Launch Info_. This includes: - - **Segment Documentation:** Using these templates ([subscription](https://hackmd.io/t7amLXluS7-39rg7ARZgSA?both=)/[stream](https://hackmd.io/TV8cZR6tRnKwGtkvSexeag), document how our mutual customers can use your integration. + - **Segment Documentation:** Using these templates ([subscription](https://hackmd.io/t7amLXluS7-39rg7ARZgSA?both=)/[stream](https://hackmd.io/TV8cZR6tRnKwGtkvSexeag), document how mutual customers can use your integration. - **Your Documentation:** Similar to the above but hosted on your own website. - - **Catalog Details:** Details for our [catalog](https://segment.com/catalog) material including screenshots by making a copy of [this template](https://docs.google.com/document/d/1kKvqYtZeDPnBjvCrtQSuO3BBH70b_CLO13hYrYIOOtA/copy). + - **Catalog Details:** Details for the [catalog](https://segment.com/catalog) material including screenshots by making a copy of [this template](https://docs.google.com/document/d/1kKvqYtZeDPnBjvCrtQSuO3BBH70b_CLO13hYrYIOOtA/copy). - **Integrations / Partners Page:** Add your Segment integration to your integrations or partners page. - **Blog Post:** Publish a launch blog post about your integration, like [this](https://www.kustomer.com/blog/kustomer-segment-integration/). Make sure you share it on Twitter and LinkedIn too! (If you don't have a blog, an email is okay) -Be sure to use our [brand kit](https://brandfolder.com/segment/press-kit) for logos, and our [UTM guide](https://docs.google.com/document/d/1L0MHYdF2SYaMMiodQCYlZELF7pN0TXiZbD22nnlGhEk/copy) any time you link to a Segment page. +Be sure to use Segment's [brand kit](https://brandfolder.com/segment/press-kit) for logos, and Segment's [UTM guide](https://docs.google.com/document/d/1L0MHYdF2SYaMMiodQCYlZELF7pN0TXiZbD22nnlGhEk/copy) any time you link to a Segment page. -You can contact us at [partner-support@segment.com](mailto:partner-support@segment.com) once you have all these elements ready for review. Once we approve them, your Destination goes live on Catalog in Public Beta 🎉 +You can contact Segment Partner Support at [partner-support@segment.com](mailto:partner-support@segment.com) once you have all these elements ready for review. Once approved, your Destination goes live on the Catalog in Public Beta. ## Post Launch Congratulations on launching your integration in Public Beta - welcome aboard! Here are the next steps to move out from Public Beta to Public: -1. Implement the [Enable with Segment OAuth](/docs/partners/enable-with-segment) button - this makes it much easier for our mutual customers to get started with your integration! -2. Onboard at least 3 customers to actively use your integration +1. Implement the [Enable with Segment OAuth](/docs/partners/enable-with-segment) button - this makes it much easier for mutual customers to get started with your integration! +2. Onboard at least three customers to actively use your integration Bonus points if you join the [Segment Select](/docs/partners/#segment-select) Partner Program! ## Segment Select -Our focus when working with partners is to ensure we are always providing an exceptional experience to our joint customers. -From there, you can start taking advantage of our available partner opportunities by [joining the Segment Select Partner Program](https://segment.com/partners/integration/#module-5-benefits). +You can taking advantage of Segment's available partner opportunities by [joining the Segment Select Partner Program](https://segment.com/partners/integration/#module-5-benefits). By becoming a Segment Select partner, you have access to sales support, technical training, and personalized co-marketing opportunities. [Learn more about the program details here.](https://assets.ctfassets.net/9u2t3ap6pctb/3NPVQDweiX0l8Z2edugwIr/d09ea71f04913f3189514b7d2df57d36/Segment_Select_Partner_Program_One_Pager.pdf) diff --git a/src/partners/plugins.md b/src/partners/plugins.md index 5f56330f56..8d8a394bd7 100644 --- a/src/partners/plugins.md +++ b/src/partners/plugins.md @@ -2,21 +2,20 @@ title: Building a Plugin --- -> info "" -> The Developer Center currently only supports the [Subscription](/docs/partners/subscriptions) component in _Developer Preview_. Include [your information here](https://airtable.com/shrT3b4C7agUEBKVS) and we'll contact you once _Plugins_ are made available! +{% include content/dev-center-note.md %} -SDK Plugins are used to augment traditional Destination and Source components ([Subscriptions](/docs/partners/subscriptions/) and [Streams](/docs/partners/streams/)) by shipping code to the End User's Device. You can use this mechanism to enable customers to dynamically include your libraries or SDKs and to wire up the Segment SDK to invoke them directly when your plugin is enabled. This pattern is most commonly used to build what we call "Device-mode Destinations". +SDK Plugins are used to augment traditional Destination and Source components ([Subscriptions](/docs/partners/subscriptions/) and [Streams](/docs/partners/streams/)) by shipping code to the End User's Device. You can use this mechanism to enable customers to dynamically include your libraries or SDKs and to wire up the Segment SDK to invoke them directly when your plugin is enabled. This pattern is most commonly used to build "Device-mode Destinations". Segment's Client SDKs (analytics.js, analytics-ios, and analytics-android) serve as "microcosms" of the Segment Customer Data Infrastructure runtime — they enable the dynamic orchestration of event collection, cleaning and validation, transforming, and delivery to collection endpoints right from inside the SDK. -SDK Plugins are an appropriate component for your App if your source or destination requires client-side side effects, such as collecting ambient data in the client (Heatmapping, Error & Performance Monitoring tools), relying on device-native context such as third party cookies (Advertising pixels), or needs to actively modify the Client UI (e.g. A/B testing, Push Notification, In-App Messaging and LiveChat). +SDK Plugins are an appropriate component for your App if your source or destination requires client-side side effects, such as collecting ambient data in the client (Heatmapping, Error & Performance Monitoring tools), relying on device-native context such as third party cookies (Advertising pixels), or needs to actively modify the Client UI (for example, A/B testing, Push Notification, In-App Messaging and LiveChat). ## Getting Started -Review the steps outlined in the [Developer Center Overview](/docs/partners). This document outlines specific details for Step 4 as it relates to building a plugin. +Review the steps outlined in the [Developer Center Overview](/docs/partners). This document outlines specific details for Step Four as it relates to building a plugin. -1. Understand Segment's [Conceptual Model](/docs/partners/conceptual-model) and [Spec](https://segment.com/docs/connections/spec). +1. Understand Segment's [Conceptual Model](/docs/partners/conceptual-model) and [Spec](/docs/connections/spec). 2. Follow Segment's security guidance. 3. Request [access to the Segment Developer Center](https://segment.com/partners/developer-center/). 4. Create an App. @@ -36,7 +35,7 @@ Once you've created an App, you're ready to starting building your Plugin. Refer * [iOS Plugin Docs](https://github.com/segmentio/analytics-ios/wiki/Writing-Integrations) + [Mixpanel iOS Plugin Example](https://github.com/segment-integrations/analytics-ios-integration-mixpanel) -As with all partner contributions, only those which follow the Segment [Spec](/docs/connections/spec) will be approved. Once you've finished building your plugin, make sure to reference the above wikis to test your plugin locally. Before reviewing, we'll need to see a full suite of cross-device tests. +As with all partner contributions, only those which follow the Segment [Spec](/docs/connections/spec) will be approved. Once you've finished building your plugin, make sure to reference the above wikis to test your plugin locally. Before reviewing, Segment needs to see a full suite of cross-device tests. ## Next Steps diff --git a/src/partners/streams.md b/src/partners/streams.md index 961523f259..bb406e2ada 100644 --- a/src/partners/streams.md +++ b/src/partners/streams.md @@ -3,7 +3,8 @@ title: Build a Stream --- > info "" -> The Developer Center currently only supports the [Subscription](/docs/partners/subscriptions) component in _Developer Preview_. Include [your information here](https://airtable.com/shrj3BkHMhdeaPYWt) and Segment will contact you once _Streams_ are made available! +> 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! + Streams enable you to send data to mutual customers from your web services in realtime. diff --git a/src/partners/subscriptions/build-functions.md b/src/partners/subscriptions/build-functions.md index ce54f942b9..5d21fa5bf4 100644 --- a/src/partners/subscriptions/build-functions.md +++ b/src/partners/subscriptions/build-functions.md @@ -5,15 +5,15 @@ redirect_from: '/partners/build-functions/' Subscription Functions allow you to write custom JavaScript code that sends Segment Event Data to existing APIs. This guides explains how to write custom functions. -> note "" -> **NOTE:** On July 31, 2021 support for building Subscription Functions will be removed from Developer Center. You may continue building a Subscription Webhook. Segment is committed to improving the Developer Center experience with Developer Center 2.0, which will offer a more holistic approach to building on Segment. If you're interested in joining the beta in the coming months, please fill out [this form](https://airtable.com/shrvZzQ6NTTwsc6rQ){:target="_blank"}. +{% include content/dev-center-note.md %} + ## Getting Started -Review the steps outlined in the [Developer Center Overview](/docs/partners). This document outlines specific details for Step 4 as it relates to building a Subscription Function. +Review the steps outlined in the [Developer Center Overview](/docs/partners). This document outlines specific details for Step four as it relates to building a Subscription Function. -1. Understand Segment's [Conceptual Model](/docs/partners/conceptual-model) and [Spec](https://segment.com/docs/connections/spec). +1. Understand Segment's [Conceptual Model](/docs/partners/conceptual-model) and [Spec](/docs/connections/spec). 2. Follow Segment's security guidance. 3. Request [access to the Segment Developer Center](https://segment.com/partners/developer-center/). 4. Create an App. @@ -29,7 +29,7 @@ Begin by selecting the _Subscription_ card in your Developer Center UI after cre ![](/docs/partners/images/developer_center_customcode_page.png) -For every event you send to Segment, Segment invokes a function you provide for the event type. So you must define functions named after every type in the [Segment Spec](https://segment.com/docs/connections/spec/) that you support: +For every event you send to Segment, Segment invokes a function you provide for the event type. So you must define functions named after every type in the [Segment Spec](/docs/connections/spec/) that you support: - `onIdentify` - `onTrack` @@ -41,7 +41,7 @@ For every event you send to Segment, Segment invokes a function you provide for The two items passed into the functions are the _event payload_ and the _settings_. All subscriptions have an _apiKey_ setting by default. To add more custom settings, go to the `Settings Builder` page under `App Info`. Use your custom setting _key_ (which is generated for you from your custom setting label) to access your custom setting from the _settings_ argument. -* The _Event_ argument to the function is the [Segment Event Data](https://segment.com/docs/connections/spec/common/#structure) +* The _Event_ argument to the function is the [Segment Event Data](/docs/connections/spec/common/#structure) * The _Settings_ argument to the function contains user settings like _apiKey_ and any custom settings you have added. The functions are ["async/await" style JavaScript](https://javascript.info/async-await), and should use the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) using the pre-loaded `fetch` package. @@ -68,13 +68,13 @@ async function onTrack(event, settings) { } ``` -The function should return data to indicates a success. In the above example we simply return the request body. +The function should return data to indicates a success. In the above example Segment returns the request body. You can also `throw` an error to indicate a failure. In the above example, try changing the endpoint to `https://foo` and you'll see it throws a `FetchError` with the message `request to https://foo/ failed, reason: getaddrinfo ENOTFOUND foo foo:443` -There are 3 pre-defined error types that you can `throw` to indicate the function ran as expected, but data could not be delivered: +There are three pre-defined error types that you can `throw` to indicate the function ran as expected, but data could not be delivered: * EventNotSupported * InvalidEventPayload @@ -178,7 +178,9 @@ The `btoa()` method creates a base-64 encoded ASCII string from a binary string. ## Test -When testing your integration, we suggest going through two separate flows - testing that your endpoint successfully ingests data in the way you would expect, and also mimicking a user implementing your integration within their Segment workspace. +When testing your integration, proceed through two separate flows: +1. Test that your endpoint successfully ingests data in the way you would expect. +2. Mimic a user implementing your integration within their Segment workspace. ### Your Endpoint diff --git a/src/partners/subscriptions/build-webhook.md b/src/partners/subscriptions/build-webhook.md index 7fb46446ec..a802079825 100644 --- a/src/partners/subscriptions/build-webhook.md +++ b/src/partners/subscriptions/build-webhook.md @@ -3,13 +3,16 @@ title: Building a Subscription Webhook redirect_from: '/partners/build-webhook/' --- +{% include content/dev-center-note.md %} + + Subscription Webhooks allow Segment Partners to ingest Segment Event Data using a webhook. This guide explains how to set up your webhook with Segment. ## Getting Started -Review the steps outlined in the [Developer Center Overview](/docs/partners). This document outlines specific details for Step 4 as it relates to building a Subscription Webhook. +Review the steps outlined in the [Developer Center Overview](/docs/partners). This document outlines specific details for Step four as it relates to building a Subscription Webhook. -1. Understand Segment's [Conceptual Model](/docs/partners/conceptual-model) and [Spec](https://segment.com/docs/connections/spec). +1. Understand Segment's [Conceptual Model](/docs/partners/conceptual-model) and [Spec](/docs/connections/spec). 2. Follow Segment's security guidance. 3. Request [access to the Segment Developer Center](https://segment.com/partners/developer-center/). 4. Create an App. @@ -35,13 +38,11 @@ The endpoint must: #### Authorization -Segment sends your user's API key with requests, and you can use it to authenticate requests. **Note**: This is the API key _you_ give to your users; it is not a Segment API key. +Segment sends your user's API key with requests, and you can use it to authenticate requests. This is the API key _you_ give to your users; it is not a Segment API key. Segment sends the key in the `Authorization` header using the `Basic` authentication type. It is Base64 encoded with your user's API key as the username, and an empty password. -For example, if your user's API key was `segment`, Segment would Base64 encode the string `'segment:'` and prepend the string `'Basic '`. - -**Note**: The colon is always present, even when the password is absent. +For example, if your user's API key was `segment`, Segment would Base64 encode the string `'segment:'` and prepend the string `'Basic '`. The colon is always present, even when the password is absent. This would result in a final string of `'Basic c2VnbWVudDo='`. This is what is contained in the `Authorization` header. Like any Authorization header, you must decode the string when you receive it. @@ -59,22 +60,22 @@ Any custom settings you add will be sent in the custom header `X-Segment-Setting Segment sends you the following HTTP headers with all requests: -Header|Description|Example -------|-----------|------- -`Accept` | Segment accepts any content type, but ignores responses unless this header is set to `application/json`.| `Accept: */*` -`Authorization`| Segment sends your user's API token in this header, with the `Basic` authentication type. | `Authorization: Basic c2VnbWVudDo=` -`Cache-Control` | Each request Segment sends is a new event, so we do not expect caching on your end.| `Cache-Control: no-cache` -`Connection` | Segment uses HTTP/1.1's keep-alive functionality whenever possible, however this is optional.| `Connection: Keep-Alive` -`Content-Length` | Segment always sends you the length of the request in bytes.| `Content-Length: 348` -`Content-Type` | Segment indicates the type of data it sent you (this will always be JSON), along with Segment's vendor type. | `Content-Type: application/json` -`User-Agent` | Segment sends you this field every time. You can count on us!| `User-Agent: Segment.io/1.0` -`X-Segment-Settings` | Except for the API key (which is sent in the Authorization header), Segment will send the base 64 encoding of the rest of your custom settings encoded in this header. | `X-Segment-Settings: eyJjdXN0b21TZXR0aW5nT25lIjoiY3VzdG9tIHNldHRpbmcgdmFsdWUifQ==` +| Header | Description | Example | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| `Accept` | Segment accepts any content type, but ignores responses unless this header is set to `application/json`. | `Accept: */*` | +| `Authorization` | Segment sends your user's API token in this header, with the `Basic` authentication type. | `Authorization: Basic c2VnbWVudDo=` | +| `Cache-Control` | Each request Segment sends is a new event. Segment does not expect your application to cache. | `Cache-Control: no-cache` | +| `Connection` | Segment uses HTTP/1.1's keep-alive functionality whenever possible, however this is optional. | `Connection: Keep-Alive` | +| `Content-Length` | Segment always sends you the length of the request in bytes. | `Content-Length: 348` | +| `Content-Type` | Segment indicates the type of data it sent you (this will always be JSON), along with Segment's vendor type. | `Content-Type: application/json` | +| `User-Agent` | Segment sends you this field every time. | `User-Agent: Segment.io/1.0` | +| `X-Segment-Settings` | Except for the API key (which is sent in the Authorization header), Segment will send the base 64 encoding of the rest of your custom settings encoded in this header. | `X-Segment-Settings: eyJjdXN0b21TZXR0aW5nT25lIjoiY3VzdG9tIHNldHRpbmcgdmFsdWUifQ==` | ### Responding to Segment Data #### Request Body -Segment's [Spec](https://segment.com/docs/connections/spec) standardizes the data that you can expect from Segment. You can choose to implement four types types of calls: +Segment's [Spec](/docs/connections/spec) standardizes the data that you can expect from Segment. You can choose to implement four types types of calls: - Who is this? `.identify(userId, traits)` - What are they doing? `.track(userId, event, properties)` @@ -105,7 +106,8 @@ For example, you might implement the `.identify(userId, traits)` call to create } ``` -*Important*: The casing on these fields will vary by customer, so be ready to accept any casing. +> info "" +> The casing on these fields will vary by customer, so be ready to accept any casing. #### Status Code @@ -114,20 +116,20 @@ Segment uses standard HTTP status code conventions to help diagnose problems qui Upon receiving data, your endpoint should reply with one of the following status codes: -Code | Reason ----- | ------ -`200` | You've accepted and successfully processed the message. -`202` | You've accepted the message, but have not yet processed it. -`400` | The message is malformed, or otherwise contains an error that is the client's fault. -`401` | The client's API key is malformed, has expired, or is otherwise no longer valid. -`403` | The client's API key is valid, but has been rejected due to inadequate permissions. -`500` | If you encounter an internal error when processing the message, reply with this code. (Hopefully you won't have to send too many of these.) -`501` | If Segment sends you an [API call type](https://segment.com/docs/connections/spec/#api-calls) (indicated by the `type` property included on all messages) you don't support, reply with this code. Read more about the API call types Segment supports [here](https://segment.com/docs/connections/spec/#api-calls). -`503` | Send Segment this code when your endpoint is temporarily down for maintenance or otherwise not accepting messages. This helps Segment avoid dropping users' messages during your downtime. +| Code | Reason | +| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `200` | You've accepted and successfully processed the message. | +| `202` | You've accepted the message, but have not yet processed it. | +| `400` | The message is malformed, or otherwise contains an error that is the client's fault. | +| `401` | The client's API key is malformed, has expired, or is otherwise no longer valid. | +| `403` | The client's API key is valid, but has been rejected due to inadequate permissions. | +| `500` | If you encounter an internal error when processing the message, reply with this code. (Hopefully you won't have to send too many of these.) | +| `501` | If Segment sends you an [API call type](https://segment.com/docs/connections/spec/#api-calls) (indicated by the `type` property included on all messages) you don't support, reply with this code. Read more about the API call types Segment supports [here](https://segment.com/docs/connections/spec/#api-calls). | +| `503` | Send Segment this code when your endpoint is temporarily down for maintenance or otherwise not accepting messages. This helps Segment avoid dropping users' messages during your downtime. | #### Response Body -You can normally send back an empty body, but when sending back a `4xx`- or `5xx`-class error, you can optionally send Segment a diagnostic message that explains the error. This message is displayed to the user in the Segment debugger, and is be used in our Event Delivery summaries. +You can normally send back an empty body, but when sending back a `4xx`- or `5xx`-class error, you can optionally send Segment a diagnostic message that explains the error. This message is displayed to the user in the Segment debugger, and is be used in Segment's Event Delivery summaries. Be sure to send JSON (and set your `Content-Type` header to `application/json`), and send your message in the `message` property. @@ -149,7 +151,9 @@ Or, if your tool requires an email address in order to accept calls, use this ex ## Test -When testing your integration, we suggest going through two separate flows - testing that your endpoint successfully ingests data in the way you would expect, and also mimicking a user implementing your integration within their Segment workspace. +When testing your integration, proceed through two separate flows: +1. Test that your endpoint successfully ingests data in the way you would expect. +2. Mimic a user implementing your integration within their Segment workspace. ### Your Endpoint @@ -174,7 +178,7 @@ To test your Destination in the Catalog, click the "Test" tab in the Developer C From here, click "Configure App", select a Source, and click "Confirm Source". You can now configure your destination by setting the "API Key", then clicking the toggle to enable the destination. -Next you can click the "Event Tester" tab to send data to your destination. Here you can see what requests Segment sends to your destination and introspect the response you are returning. Learn more about the event tester [here](https://segment.com/docs/guides/best-practices/how-do-I-test-my-connections/). +Next you can click the "Event Tester" tab to send data to your destination. Here you can see what requests Segment sends to your destination and introspect the response you are returning. Learn more about the event tester [here](/docs/guides/best-practices/how-do-I-test-my-connections/). Now you can use the JavaScript SDK in a browser to generate real analytics events. diff --git a/src/partners/subscriptions/index.md b/src/partners/subscriptions/index.md index 5e8fc5381b..b95c5ef23d 100644 --- a/src/partners/subscriptions/index.md +++ b/src/partners/subscriptions/index.md @@ -2,15 +2,18 @@ title: Subscription Overview --- -Subscriptions enable you to receive incoming data for our mutual customers to your service's HTTPS endpoint in realtime. +{% include content/dev-center-note.md %} -A Subscription gives you complete control over how you want to store, transform and process the data. It means that our mutual customers can immediately start sending you data from any one of Segment's [sources](/docs/connections/sources/), including a web browser, mobile apps, or from our mutual customer's servers — with no added work. Segment Business Tier customers can also [replay historical data](/docs/guides/what-is-replay/), which means you can demonstrate the value of your tool rapidly. + +Subscriptions enable you to receive incoming data for mutual customers to your service's HTTPS endpoint in real-time. + +A Subscription gives you complete control over how you want to store, transform and process the data. It means that mutual customers can immediately start sending you data from any one of Segment's [sources](/docs/connections/sources/), including a web browser, mobile apps, or from mutual customer's servers — with no added work. Segment Business Tier customers can also [replay historical data](/docs/guides/what-is-replay/), which means you can demonstrate the value of your tool rapidly. ## Getting Started -Review the steps outlined in the [Developer Center Overview](/docs/partners). This document outlines specific details for Step 4 as it relates to building a subscription. +Review the steps outlined in the [Developer Center Overview](/docs/partners). This document outlines specific details for Step four as it relates to building a subscription. -1. Understand Segment's [Conceptual Model](/docs/partners/conceptual-model) and [Spec](https://segment.com/docs/connections/spec). +1. Understand Segment's [Conceptual Model](/docs/partners/conceptual-model) and [Spec](/docs/connections/spec). 2. Follow Segment's security guidance. 3. Request [access to the Segment Developer Center](https://segment.com/partners/developer-center/). 4. Create an App. @@ -24,4 +27,4 @@ Review the steps outlined in the [Developer Center Overview](/docs/partners). Th > note "" > **NOTE:** On July 31, 2021 support for building Subscription Functions was removed from Developer Center. You may continue building [Subscription Webhooks](/docs/partners/subscriptions/build-webhook) in place of Subscription Functions. Work has begun on Developer Center 2.0 which will offer a more holistic approach to building on Segment. If you're interested in joining the beta in the coming months, please fill out [this form](https://airtable.com/shrvZzQ6NTTwsc6rQ){:target="_blank"}! -[Subscription Webhooks](/docs/partners/subscriptions/build-webhook) allow you to build a new HTTP service that receives Webhook POSTs from Segment. Read more in-depth technical details about building in [our documentation here](/docs/partners/subscriptions/build-webhook). +[Subscription Webhooks](/docs/partners/subscriptions/build-webhook) allow you to build a new HTTP service that receives Webhook POSTs from Segment. Read more in-depth technical details about building webhooks [here](/docs/partners/subscriptions/build-webhook). diff --git a/vale-styles/Vocab/Docs/accept.txt b/vale-styles/Vocab/Docs/accept.txt index 8a8556f05d..3c96311dba 100644 --- a/vale-styles/Vocab/Docs/accept.txt +++ b/vale-styles/Vocab/Docs/accept.txt @@ -1,9 +1,11 @@ (?:C|c)annonical (?:C|c)onfig +(?:C|c)rypto (?:D|d)eduplicate (?:D|d)eduplication (?:G|g)tag (?:K|k)laviyo +(?:L|l)odash (?:L|l)ookback (?:P|p)ageviews?\b (?:P|p)endo @@ -19,6 +21,7 @@ allowlist Amberflo Appboy Appsflyer +async Blitzllama blocklist boolean @@ -38,6 +41,7 @@ Friendbuy ga gmail Gradle +Heatmapping href html http @@ -82,6 +86,7 @@ utm Vero Vidora viewability +waitlist WebKit Wootric Zendesk \ No newline at end of file