From 69ebd8d7dcd5568c8c7d9a15147f3631972444c9 Mon Sep 17 00:00:00 2001 From: forstisabella <92472883+forstisabella@users.noreply.github.com> Date: Mon, 8 Sep 2025 17:36:51 -0400 Subject: [PATCH 1/2] Update typewriter.md --- .../apis-and-extensions/typewriter.md | 79 ++++++++++--------- 1 file changed, 41 insertions(+), 38 deletions(-) diff --git a/src/protocols/apis-and-extensions/typewriter.md b/src/protocols/apis-and-extensions/typewriter.md index aee51d95d9..a3ac6ddae0 100644 --- a/src/protocols/apis-and-extensions/typewriter.md +++ b/src/protocols/apis-and-extensions/typewriter.md @@ -4,7 +4,7 @@ redirect_from: '/protocols/typewriter/' --- > warning "" -> Typewriter for analytics.js and analytics-node will receive no new features and only critical maintenance updates from Segment. Typewriter for other libraries and SDKs are not actively maintained by Segment. Typewriter is available on [GitHub](https://github.com/segmentio/typewriter/){:target="_blank”} under the MIT license for the open-source community to fork and contribute. +> Typewriter for Analytics.js and Analytics-Node will receive no new features and only critical maintenance updates from Segment. Typewriter for other libraries and SDKs are not actively maintained by Segment. Typewriter is available on [GitHub](https://github.com/segmentio/typewriter/){:target="_blank”} under the MIT license for the open-source community to fork and contribute. [Typewriter](https://github.com/segmentio/typewriter){:target="_blank”} is a tool for generating strongly-typed Segment analytics libraries based on your pre-defined [Tracking Plan](/docs/protocols/tracking-plan) spec. @@ -12,7 +12,7 @@ At a high-level, Typewriter can take an event from your Tracking Plan like this ![Order Completed Event in a Protocols Tracking Plan](images/typewriter-order-completed.png) -Typewriter uses the event to generate a typed analytics call in different languages: +Typewriter uses the event to generate a typed Analytics call in different languages: ```ts // Example client in your web app @@ -34,9 +34,9 @@ SEGTypewriterAnalytics.orderCompleted( > info "" > Typewriter can generate clients for `analytics.js`, `analytics-node`, `analytics-swift` and `analytics-kotlin`. -These generated clients are embedded with metadata from your Tracking Plan, which contextualizes your analytics instrumentation, and reduces (or entirely eliminates!) incorrect instrumentations in your production environments. In your editor, you can access event names, descriptions, property names, types and more: +These generated clients are embedded with metadata from your Tracking Plan, which contextualizes your analytics instrumentation, and reduces (or entirely eliminates) incorrect instrumentations in your production environments. In your editor, you can access event names, descriptions, property names, types and more: -![Event name intellisense](images/typewriter-event-names.png) +![Event name intelli-sense](images/typewriter-event-names.png) You can also configure Typewriter to validate analytic events at runtime, which can alert you to instrumentation errors during development and testing. Typewriter can warn you about missing required properties, invalid enum values, regex mismatches, and any other advanced [JSON Schema](https://json-schema.org/understanding-json-schema/) you configure in your Tracking Plan. @@ -46,11 +46,11 @@ You can use this with a test suite to automatically fail your unit tests if the ![Example unit tests failing because of violations](images/typewriter-test-suite.png) -If you use a statically typed language (such as TypeScript, Java, Objective-C, or Swift), you get access to compile-time warnings about your instrumentation: +If you use a statically typed language (like TypeScript, Java, Objective-C, or Swift), you get access to compile-time warnings about your instrumentation: ![Example compile-time validation warnings](images/typewriter-compile-time-warnings.png) -Typewriter also helps teams adopt [analytics best practices](/docs/protocols/tracking-plan/best-practices/), such as avoiding autogenerated event names, and carefully considering what properties are tracked. +Typewriter also helps teams adopt [Analytics best practices](/docs/protocols/tracking-plan/best-practices/), like avoiding autogenerated event names and carefully considering what properties are tracked. To get started, check out one of the quickstart guides below: - [Browser Quickstart](#browser-quickstart) @@ -66,7 +66,7 @@ Have feedback on Typewriter? Consider opening a [GitHub Issue in the @segmentio/ ## Prerequisites -Typewriter is built using [Node.js](https://nodejs.org/en/){:target="_blank”}, and requires node >= 14.x +Typewriter is built using [Node.js](https://nodejs.org/en/){:target="_blank”}, and requires node >= 14.x. You can check if you have Node and NPM installed by running the following commands in your command-line window: @@ -83,11 +83,11 @@ $ brew install node Once you've installed Node and NPM, run the `--version` commands again to verify that they were installed correctly. -## Browser Quickstart +## Browser quickstart To get started with Typewriter in your browser: -1. Make sure you have `node` installed using the instructions in the [prerequisites](#prerequisites) above. -2. Install `analytics.js` in your app. There are two methods. +1. Make sure you have `node` installed using the instructions in the [prerequisites](#prerequisites). +2. Install `analytics.js` in your app using one of the following methods: - **Snippet method (most common)**: Paste the snippet in the[`Step 1: Copy the Snippet`](/docs/connections/sources/catalog/libraries/website/javascript/quickstart/#step-2-copy-the-segment-snippet) from the [`analytics.js` Quickstart Guide](/docs/connections/sources/catalog/libraries/website/javascript/quickstart/). - **NPM method**: Load analytics.js with the npm library. Learn more about using the npm method in the [@segmentio/analytics-next](https://github.com/segmentio/analytics-next/tree/master/packages/browser#readme){:target="_blank”} repository. @@ -138,7 +138,7 @@ To get started with Typewriter in your browser: > info "" > Run `npx typewriter` to regenerate your Typewriter client. You need to do this each time you update your Tracking Plan. -To help you minimize your bundle size, Typewriter supports [tree-shaking](https://webpack.js.org/guides/tree-shaking/){:target="_blank"} using named exports. All generated analytics calls generate and export automatically, so you can import them like so: +To help you minimize your bundle size, Typewriter supports [tree-shaking](https://webpack.js.org/guides/tree-shaking/){:target="_blank"} using named exports. All generated analytics calls generate and export automatically, so you can import them like this: ```ts import { orderCompleted } from './analytics' @@ -149,12 +149,12 @@ orderCompleted({ }) ``` -Typewriter wraps your analytics calls in an [ES6 `Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy){:target="_blank"}, which helps protect your application from crashing if you make analytics calls with a generated function that doesn't exist. For example, if an `Order Completed` event didn't exist in your Tracking Plan in the first example above, then your app would crash with a `TypeError: typewriter.orderCompleted is not a function`. However, since Typewriter dynamically proxies the underlying function calls, it can detect if a function doesn't exist, and handle it for you. Typewriter logs a warning message, then fires an `Unknown Analytics Call Fired` event into your source. This helps to prevent regressions when you migrate JavaScript projects to Typewriter in bulk. Keep in mind that proxying doesn't work with named exports. +Typewriter wraps your analytics calls in an [ES6 `Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy){:target="_blank"}, which helps protect your application from crashing if you make analytics calls with a generated function that doesn't exist. For example, if an `Order Completed` event didn't exist in your Tracking Plan in the first example above, then your app would crash with a `TypeError: typewriter.orderCompleted is not a function` error. However, since Typewriter dynamically proxies the underlying function calls, it can detect if a function doesn't exist, and handle it for you. Typewriter logs a warning message, then fires an `Unknown Analytics Call Fired` event into your source. This helps to prevent regressions when you migrate JavaScript projects to Typewriter in bulk. Keep in mind that proxying doesn't work with named exports. -## Node.js Quickstart +## Node.js quickstart To get started with Node.js: -1. Make sure you have `node` installed using the instructions in the [prerequisites](#prerequisites) above. +1. Make sure you have `node` installed using the instructions in the [prerequisites](#prerequisites). 2. Install `@segment/analytics-node` in your app. For now, you just need to complete [`Step 2: Install the Module`](/docs/connections/sources/catalog/libraries/server/node/quickstart/#step-2-install-the-module) from the [`analytics-node` Quickstart Guide](/docs/connections/sources/catalog/libraries/server/node/quickstart). 3. Once you have `analytics-node` installed, add Typewriter as a developer dependency in your project: @@ -162,7 +162,7 @@ To get started with Node.js: $ npm install --save-dev typewriter ``` -4. Run `npx typewriter init` to use the Typewriter quickstart wizard that generates a [`typewriter.yml`](#configuration-reference) configuration, along with your first Typewriter client. When you run the command, it creates a `typewriter.yml` file in your repo. For more information on the format of this file, see the [Typewriter Configuration Reference](#configuration-reference). The command also adds a new Typewriter client in `./analytics` (or whichever path you configured). You can import this client into your project, like so: +4. Run `npx typewriter init` to use the Typewriter quickstart wizard that generates a [`typewriter.yml`](#configuration-reference) configuration, along with your first Typewriter client. When you run the command, it creates a `typewriter.yml` file in your repository. For more information on the format of this file, see the [Typewriter Configuration Reference](#configuration-reference). The command also adds a new Typewriter client in `./analytics` (or whichever path you configured). You can import this client into your project, like so: ```ts // Initialize analytics-node, per the analytics-node guide above. @@ -193,15 +193,15 @@ To get started with Node.js: Typewriter wraps your analytics calls in an [ES6 `Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy){:target="_blank”}, which helps protect your application from crashing if you make analytics calls with a generated function that doesn't exist. For example, if an `Order Completed` event didn't exist in your Tracking Plan in the first example above, then your app would crash with a `TypeError: typewriter.orderCompleted is not a function`. However, since `typewriter` dynamically proxies the underlying function calls, it can detect if a function does not exist, and handle it for you. Typewriter logs a warning message, then fires an `Unknown Analytics Call Fired` event into your source. This helps to prevent regressions when you migrate JavaScript projects to Typewriter in bulk. Keep in mind that proxying doesn't work with named exports. -## Swift Quickstart +## Swift quickstart > info "" > For use with the `analytics-ios` SDK, use [Typewriter v7](/docs/protocols/apis-and-extensions/typewriter-v7). To get started using Typewriter with Swift: -1. Make sure you have `node` installed using the instructions in the [prerequisites](#prerequisites) above. +1. Make sure you have `node` installed using the instructions in the [prerequisites](#prerequisites). 2. Install `analytics-swift` in your app. Follow the [analytics-swift Quickstart Guide](/docs/connections/sources/catalog/libraries/mobile/swift). -3. Run `npx typewriter init` to use the Typewriter quickstart wizard that generates a [`typewriter.yml`](#configuration-reference) configuration, along with your first Typewriter client. When you run the command, it creates a `typewriter.yml` file in your repo. For more information on the format of this file, see the [Typewriter Configuration Reference](#configuration-reference). +3. Run `npx typewriter init` to use the Typewriter quickstart wizard that generates a [`typewriter.yml`](#configuration-reference) configuration, along with your first Typewriter client. When you run the command, it creates a `typewriter.yml` file in your repository. For more information on the format of this file, see the [Typewriter Configuration Reference](#configuration-reference).
**Note:** Run `npx typewriter` to regenerate your Typewriter client. You need to do this each time you update your Tracking Plan. @@ -216,15 +216,15 @@ To get started using Typewriter with Swift: )) ``` -## Kotlin Quickstart +## Kotlin quickstart > info "" > For use with the `analytics-android` SDK, use [Typewriter v7](/docs/protocols/apis-and-extensions/typewriter-v7). To get started using Typewriter with Kotlin: -1. Make sure you have `node` installed. Use the instructions in the [prerequisites](#prerequisites) above. +1. Make sure you have `node` installed. Use the instructions in the [prerequisites](#prerequisites). 2. Install `analytics-kotlin` in your app. Follow the [analytics-kotlin QuickStart Guide](/docs/connections/sources/catalog/libraries/mobile/kotlin-android/#getting-started). -3. Run `npx typewriter init`. This command enables you to use the Typewriter quickstart wizard that generates a [`typewriter.yml`](#configuration-reference) configuration, along with your first Typewriter client. The command creates a `typewriter.yml` file in your repo. For more information on the format of this file, see the [Typewriter Configuration Reference](#configuration-reference). +3. Run `npx typewriter init`. This command enables you to use the Typewriter quickstart wizard that generates a [`typewriter.yml`](#configuration-reference) configuration, along with your first Typewriter client. The command creates a `typewriter.yml` file in your repository. For more information on the format of this file, see the [Typewriter Configuration Reference](#configuration-reference). Typewriter creates the class file with the package name `typewriter`. Segment recommends you to enter the right package name during `npx typewriter init` by choosing to review the Advanced Options for Kotlin. You can also enter the right package name directly in `typewriter.yml`: @@ -234,7 +234,7 @@ To get started using Typewriter with Kotlin: sdk: kotlin languageOptions: package: com.segment.typewriter -``` + ``` > info "" > Run `npx typewriter` to regenerate your Typewriter client. You need to do this each time you update your Tracking Plan. @@ -242,11 +242,13 @@ To get started using Typewriter with Kotlin: You can now use your Typewriter client in your Android Kotlin or Java application as extensions to any `Analytics` object: Kotlin: + ```kotlin // Import your auto-generated Typewriter client: import com.segment.generated.* analytics.orderCompleted(OrderCompleted(orderID = "110", total = 39.98)) ``` + Java: ```java // Import your auto-generated Typewriter client: @@ -261,7 +263,7 @@ TypewriterAnalytics.with(this).orderCompleted( ); ``` -## React Native Quickstart +## React Native quickstart To get started with React Native: 1. Follow the [Getting Started guide for React Native](/docs/connections/sources/catalog/libraries/mobile/react-native/). @@ -273,7 +275,7 @@ To get started with React Native: 3. Run `npx typewriter init` to use the Typewriter quickstart wizard that generates a `typewriter.yml` configuration along with your first Typewriter client. - This command creates a `typewriter.yml` file in your repo. For more information on the format of this file, see the [Typewriter Configuration Reference](#configuration-reference). The command also adds a new Typewriter / Segment client in `./analytics` (or whichever path you configured). You can use this interchangeably as a normal React Native Segment client. It contains additional methods for your tracking plan: + This command creates a `typewriter.yml` file in your repository. For more information on the format of this file, see the [Typewriter Configuration Reference](#configuration-reference). The command also adds a new Typewriter/Segment client in `./analytics` (or whichever path you configured). You can use this interchangeably as a normal React Native Segment client. It contains additional methods for your tracking plan: ```ts import { @@ -318,10 +320,11 @@ To get started with React Native: // Remember this is just an extended client with the typewriter methods so all the normal segment methods still work! segmentClient.track('Untyped event'); ``` + > info "" > Run `npx typewriter` to regenerate your Typewriter client. You need to do this each time you update your Tracking Plan. -## Adding Events +## Adding events To update or add a new event to a Typewriter client, first apply your changes to your Tracking Plan. Then run the following: @@ -330,12 +333,12 @@ To update or add a new event to a Typewriter client, first apply your changes to $ npx typewriter ``` -## API Token Configuration +## API token configuration Typewriter requires a Segment API token to fetch Tracking Plans from the [Segment Public API](https://docs.segmentapis.com/){:target="_blank”}. -You must be a workspace owner to create Segment API tokens. +You must have the [Workspace Owner role](/docs/segment-app/iam/roles/) to create Segment API tokens. To create an API token: 1. Click on the **Tokens** tab on the [Access Management](https://app.segment.com/goto-my-workspace/settings/access-management){:target="_blank”} page and click **Create Token**. @@ -343,16 +346,16 @@ To create an API token: 3. Add a description for the token and assign access. If you choose *Workspace Member*, you only need to select **Tracking Plan Read-Only** for the Resource Role, as Typewriter only needs the *Tracking Plan Read-Only* role. 4. Click **Create**. -Typewriter looks for an API token in three ways, in the following order: +Typewriter looks for an API token in the following order: 1. If a token is piped through, it will use that token. For example, `echo $TW_TOKEN | typewriter build`. 2. Typewriter executes a token script from the `typewriter.yml`. See [Token Script](#token-script) for more information. 3. Typewriter reads the contents of the `~/.typewriter` file. The quickstart wizard prompts you for an API token and stores it in `~/.typewriter` for you. -Segment recommends you use a [Token Script](#token-script) to share an API token with your team. When you use a token script, you can supply your API token as an environment variable (`echo $TYPEWRITER_TOKEN`), from an `.env.` file (`source .env; echo $TYPEWRITER_TOKEN`) or using any other CLI tool for providing secrets. +We recommend you use a [Token Script](#token-script) to share an API token with your team. When you use a token script, you can supply your API token as an environment variable (`echo $TYPEWRITER_TOKEN`), from an `.env.` file (`source .env; echo $TYPEWRITER_TOKEN`) or using any other CLI tool for providing secrets. -Segment also recommends you to pipe through your API Token as this will let you keep your token secret, but it also allows you to share it across your team. +We also recommend you to pipe through your API Token as this will let you keep your token secret, but it also allows you to share it across your team. > warning "" > Segment is temporarily keeping the Token Script execution for compatibility purposes. Segment might deprecate this feature in the future, and encourages you to execute your script and pipe in the token. For example, `echo $TW_TOKEN | typewriter build`. @@ -387,9 +390,9 @@ Android Studio does not require any extra configuration and shows intellisense o ## Best Practices -Segment **strongly recommends** that you store your Tracking Plan (`plan.json`) in a version control system. This guarantees that Typewriter will generate the same client, regardless of any changes you make to your Tracking Plan in the Segment app. Otherwise, changes to your Tracking Plan could lead to broken builds. +We **strongly recommend** that you store your Tracking Plan (`plan.json`) in a version control system. This guarantees that Typewriter will generate the same client, regardless of any changes you make to your Tracking Plan in the Segment app. Otherwise, changes to your Tracking Plan could lead to broken builds. -Segment recommends that you only check in the `plan.json`, and generate your Typewriter client during the application build step (by calling `npx typewriter`). You can do this in `git` with the following `.gitignore`: +We recommend that you only check in the `plan.json`, and generate your Typewriter client during the application build step (by calling `npx typewriter`). You can do this in `git` with the following `.gitignore`: ```bash # Make sure to update `analytics` to the full path to your Typewriter client. @@ -401,7 +404,7 @@ If this isn't possible you can also check in the full generated client. Segment, ## Configuration Reference -Typewriter stores its configuration in a `typewriter.yml` file in the root of your repo. A sample configuration might look like this: +Typewriter stores its configuration in a `typewriter.yml` file in the root of your repository. A sample configuration might look like this: ```yml # Segment Typewriter Configuration Reference (https://github.com/segmentio/typewriter) @@ -478,7 +481,7 @@ To learn more about the `typewriter.yml` configuration format, see the [Configur ## Connecting to CI -As mentioned in the [Best Practices](#best-practices) section above, Segment recommends that you only check in the `plan.json`, and not the generated clients, into your version control. Instead, Segment recommends building these clients as part of the build step for your application. +As mentioned in the [Best Practices](#best-practices) section above, we recommend that you only check in the `plan.json`, and not the generated clients, into your version control. Instead, we recommend building these clients as part of the build step for your application. In your CI environment, this usually involves a step to build the Typewriter client. Make sure to build the production client before deploying the application, as explained in the [Tracking Plan Violation Handling](#tracking-plan-violation-handling) section below. @@ -509,7 +512,7 @@ $ npx typewriter production > info "Run-time validation support" > Not all languages support run-time validation. Currently, `analytics.js` and `analytics-node` support it using [AJV](https://github.com/epoberezkin/ajv){:target="_blank”} (both for JavaScript and TypeScript projects) while `analytics-ios` and `analytics-android` do not yet support run-time validation. Typewriter also doesn't support run-time validation using Common JSON Schema. For languages that don't support run-time validation, the development and production clients are identical. -Segment recommends you to use a development build when testing your application locally, or when running tests. Segment generally recommends _against_ using a development build in production, since this includes a full copy of your Tracking Plan which can increase the size of the application. +We recommend you to use a development build when testing your application locally, or when running tests. We generally recommend _against_ using a development build in production, since this includes a full copy of your Tracking Plan which can increase the size of the application. You can provide a custom handler that fires whenever a violation is seen. By default, this handler logs a warning. @@ -566,14 +569,14 @@ typewriter.setTypewriterOptions({ ## Known Limitations -Typewriter only supports `track` calls. However, you can continue to use the underlying (untyped) analytics instance to perform `identify`, `group`, `page`, `screen`, and `alias` calls. +Typewriter only supports Track calls. However, you can continue to use the underlying (untyped) analytics instance to perform Identify, Group, Page, Screen, and Alias calls. Not all languages support run-time validation. Currently, `analytics.js` and `analytics-node` support it using [AJV](https://github.com/epoberezkin/ajv){:target="_blank"} (both for JavaScript and TypeScript projects) while `analytics-swift` and `analytics-kotlin` don't support run-time validation. Typewriter also does not support event validation using the Common JSON Schema. ## Contributing -If you're interested in contributing, [open an issue on GitHub](https://github.com/segmentio/typewriter/issues/new){:target="_blank”} and Segment can help provide you pointers to get started. +If you're interested in contributing, [open an issue on GitHub](https://github.com/segmentio/typewriter/issues/new){:target="_blank”} and we can help provide you pointers to get started. ## Feedback -Segment welcomes feedback you may have on your experience with Typewriter. To contact Segment, [open an issue on GitHub](https://github.com/segmentio/typewriter/issues/new){:target="_blank”}. +We welcome feedback you may have on your experience with Typewriter. To contact us, [open an issue on GitHub](https://github.com/segmentio/typewriter/issues/new){:target="_blank”}. From 2a603faaae81b03ce25c39885b37296b72c4601a Mon Sep 17 00:00:00 2001 From: forstisabella <92472883+forstisabella@users.noreply.github.com> Date: Tue, 9 Sep 2025 14:49:33 -0400 Subject: [PATCH 2/2] Apply suggestions from code review --- src/protocols/apis-and-extensions/typewriter.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/protocols/apis-and-extensions/typewriter.md b/src/protocols/apis-and-extensions/typewriter.md index a3ac6ddae0..676811cf0e 100644 --- a/src/protocols/apis-and-extensions/typewriter.md +++ b/src/protocols/apis-and-extensions/typewriter.md @@ -353,9 +353,9 @@ Typewriter looks for an API token in the following order: The quickstart wizard prompts you for an API token and stores it in `~/.typewriter` for you. -We recommend you use a [Token Script](#token-script) to share an API token with your team. When you use a token script, you can supply your API token as an environment variable (`echo $TYPEWRITER_TOKEN`), from an `.env.` file (`source .env; echo $TYPEWRITER_TOKEN`) or using any other CLI tool for providing secrets. +Segment recommends you use a [Token Script](#token-script) to share an API token with your team. When you use a token script, you can supply your API token as an environment variable (`echo $TYPEWRITER_TOKEN`), from an `.env.` file (`source .env; echo $TYPEWRITER_TOKEN`) or using any other CLI tool for providing secrets. -We also recommend you to pipe through your API Token as this will let you keep your token secret, but it also allows you to share it across your team. +Segment also recommends you to pipe through your API Token as this will let you keep your token secret, but it also allows you to share it across your team. > warning "" > Segment is temporarily keeping the Token Script execution for compatibility purposes. Segment might deprecate this feature in the future, and encourages you to execute your script and pipe in the token. For example, `echo $TW_TOKEN | typewriter build`. @@ -390,9 +390,9 @@ Android Studio does not require any extra configuration and shows intellisense o ## Best Practices -We **strongly recommend** that you store your Tracking Plan (`plan.json`) in a version control system. This guarantees that Typewriter will generate the same client, regardless of any changes you make to your Tracking Plan in the Segment app. Otherwise, changes to your Tracking Plan could lead to broken builds. +Segment **strongly recommends** that you store your Tracking Plan (`plan.json`) in a version control system. This guarantees that Typewriter will generate the same client, regardless of any changes you make to your Tracking Plan in the Segment app. Otherwise, changes to your Tracking Plan could lead to broken builds. -We recommend that you only check in the `plan.json`, and generate your Typewriter client during the application build step (by calling `npx typewriter`). You can do this in `git` with the following `.gitignore`: +Segment recommends that you only check in the `plan.json`, and generate your Typewriter client during the application build step (by calling `npx typewriter`). You can do this in `git` with the following `.gitignore`: ```bash # Make sure to update `analytics` to the full path to your Typewriter client. @@ -481,7 +481,7 @@ To learn more about the `typewriter.yml` configuration format, see the [Configur ## Connecting to CI -As mentioned in the [Best Practices](#best-practices) section above, we recommend that you only check in the `plan.json`, and not the generated clients, into your version control. Instead, we recommend building these clients as part of the build step for your application. +As mentioned in the [Best Practices](#best-practices) section above, Segment recommends that you only check in the `plan.json`, and not the generated clients, into your version control. Instead, Segment recommends building these clients as part of the build step for your application. In your CI environment, this usually involves a step to build the Typewriter client. Make sure to build the production client before deploying the application, as explained in the [Tracking Plan Violation Handling](#tracking-plan-violation-handling) section below. @@ -512,7 +512,7 @@ $ npx typewriter production > info "Run-time validation support" > Not all languages support run-time validation. Currently, `analytics.js` and `analytics-node` support it using [AJV](https://github.com/epoberezkin/ajv){:target="_blank”} (both for JavaScript and TypeScript projects) while `analytics-ios` and `analytics-android` do not yet support run-time validation. Typewriter also doesn't support run-time validation using Common JSON Schema. For languages that don't support run-time validation, the development and production clients are identical. -We recommend you to use a development build when testing your application locally, or when running tests. We generally recommend _against_ using a development build in production, since this includes a full copy of your Tracking Plan which can increase the size of the application. +Segment recommends you to use a development build when testing your application locally, or when running tests. Segment generally recommends _against_ using a development build in production, since this includes a full copy of your Tracking Plan which can increase the size of the application. You can provide a custom handler that fires whenever a violation is seen. By default, this handler logs a warning. @@ -575,8 +575,8 @@ Not all languages support run-time validation. Currently, `analytics.js` and `an ## Contributing -If you're interested in contributing, [open an issue on GitHub](https://github.com/segmentio/typewriter/issues/new){:target="_blank”} and we can help provide you pointers to get started. +If you're interested in contributing, [open an issue on GitHub](https://github.com/segmentio/typewriter/issues/new){:target="_blank”} and Segment can help provide you pointers to get started. ## Feedback -We welcome feedback you may have on your experience with Typewriter. To contact us, [open an issue on GitHub](https://github.com/segmentio/typewriter/issues/new){:target="_blank”}. +Segment welcomes feedback you may have on your experience with Typewriter. To contact us, [open an issue on GitHub](https://github.com/segmentio/typewriter/issues/new){:target="_blank”}.