|
| 1 | +--- |
| 2 | +title: 'Typewriter v7' |
| 3 | +hidden: true |
| 4 | +--- |
| 5 | + |
| 6 | +Analytics-iOS and Analytics-Android only works with Typewriter v7. If you'd like to upgrade to the latest version of Typewriter, upgrade to [Analytics-Swift](/docs/protocols/apis-and-extensions/typewriter/#swift-quickstart) or [Analytics-Kotlin](/docs/protocols/apis-and-extensions/typewriter/#kotlin-quickstart). |
| 7 | + |
| 8 | +## Prerequisites |
| 9 | + |
| 10 | +Typewriter is built using [Node.js ](https://nodejs.org/en/), and requires `[email protected]` or later, and `[email protected]` or later to function. |
| 11 | + |
| 12 | +You can check if you have Node and NPM installed by running the following commands in your command-line window: |
| 13 | + |
| 14 | +```sh |
| 15 | +$ node --version |
| 16 | +v10.15.3 |
| 17 | + |
| 18 | +$ npm --version |
| 19 | +6.9.0 |
| 20 | + |
| 21 | +$ npx --version |
| 22 | +6.9.0 |
| 23 | +``` |
| 24 | + |
| 25 | +If you don't have these, [you'll need to install `node`](https://nodejs.org/en/download/package-manager). Installing `node` also installs `npm` and `npx` for you. If you're on macOS, you can install it with [Homebrew](https://brew.sh/): |
| 26 | + |
| 27 | +```sh |
| 28 | +$ brew install node |
| 29 | +``` |
| 30 | + |
| 31 | +Once you've installed Node and NPM, run the `--version` commands again to verify that they were installed correctly. |
| 32 | + |
| 33 | +## iOS Quickstart |
| 34 | + |
| 35 | +To get started using Typewriter with iOS: |
| 36 | +1. Make sure you have `node` installed using the instructions in the [prerequisites](#prerequisites) above. |
| 37 | +2. Install `analytics-ios` in your app. You just need to complete [`Step 1: Install the SDK`](/docs/connections/sources/catalog/libraries/mobile/ios/quickstart/#step-2-install-the-sdk) from the [`analytics-ios` Quickstart Guide](/docs/connections/sources/catalog/libraries/mobile/ios/quickstart). |
| 38 | +3. Run `npx typewriter@7 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). |
| 39 | + |
| 40 | +> note "" |
| 41 | +> Run `npx typewriter` to regenerate your Typewriter client. You need to do this each time you update your Tracking Plan. |
| 42 | +
|
| 43 | +You can now import your new Typewriter client into your project using XCode. If you place your generated files into a folder in your project, import the project as a group not a folder reference. |
| 44 | + |
| 45 | +To use your Typewriter client in an Objective-C application: |
| 46 | + |
| 47 | +```objc |
| 48 | +// Import your auto-generated Typewriter client: |
| 49 | +#import "SEGTypewriterAnalytics.h" |
| 50 | + |
| 51 | +// Issue your first Typewriter track call! |
| 52 | +[SEGTypewriterAnalytics orderCompletedWithOrderID: "ck-f306fe0e-cc21-445a-9caa-08245a9aa52c" total: @39.99]; |
| 53 | +``` |
| 54 | +
|
| 55 | +To use your Typewriter client in a Swift application, add a [Bridging Header](https://developer.apple.com/documentation/swift/imported_c_and_objective-c_apis/importing_objective-c_into_swift) like the example below: |
| 56 | +
|
| 57 | +```objc |
| 58 | +// TypewriterSwiftExample-Bridging-Header.h |
| 59 | +// |
| 60 | +// Make sure to include all generated headers from your Typewriter client: |
| 61 | +#import "Analytics/SEGTypewriterAnalytics.h" |
| 62 | +#import "Analytics/SEGGarage.h" |
| 63 | +#import "Analytics/SEGObjectItem.h" |
| 64 | +#import "Analytics/SEGOccupantsItem.h" |
| 65 | +#import "Analytics/SEGSubterraneanLab.h" |
| 66 | +#import "Analytics/SEGTunnel.h" |
| 67 | +#import "Analytics/SEGUniverse.h" |
| 68 | +#import "Analytics/SEGUniverseCharactersItemItem.h" |
| 69 | +``` |
| 70 | + |
| 71 | +Then, you can use your Typewriter client in Swift: |
| 72 | + |
| 73 | +```objc |
| 74 | +// Issue your first Typewriter track call! |
| 75 | +SEGTypewriterAnalytics.orderCompleted( |
| 76 | + orderID: "ck-f306fe0e-cc21-445a-9caa-08245a9aa52c", |
| 77 | + total: 39.99 |
| 78 | +) |
| 79 | +``` |
| 80 | + |
| 81 | +## Android Quickstart |
| 82 | + |
| 83 | +To get started using Typewriter with Android: |
| 84 | +1. Make sure you have `node` installed using the instructions in the [prerequisites](#prerequisites) above. |
| 85 | +2. Install `analytics-android` in your app, and configure the singleton analytics instance by following the first three steps in in the [Android Quickstart](/docs/connections/sources/catalog/libraries/mobile/android/quickstart/#step-2-install-the-library). |
| 86 | +3. Run `npx typewriter@7 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). |
| 87 | + |
| 88 | +> note "" |
| 89 | +> You can regenerate your Typewriter client by running `npx typewriter`. You need to do this each time you update your Tracking Plan. |
| 90 | +
|
| 91 | +You can now use your Typewriter client in your Android Java application: |
| 92 | + |
| 93 | +```java |
| 94 | +// Import your auto-generated Typewriter client: |
| 95 | +import com.segment.generated.* |
| 96 | + |
| 97 | +// Issue your first Typewriter track call! |
| 98 | +TypewriterAnalytics.with(this).orderCompleted( |
| 99 | + OrderCompleted.Builder() |
| 100 | + .orderID("ck-f306fe0e-cc21-445a-9caa-08245a9aa52c") |
| 101 | + .total(39.99) |
| 102 | + .build() |
| 103 | +); |
| 104 | +``` |
| 105 | + |
| 106 | +## Adding Events |
| 107 | + |
| 108 | +To update or add a new event to a Typewriter client, first apply your changes to your Tracking Plan. Then run the following: |
| 109 | + |
| 110 | +```sh |
| 111 | +# Run this in the directory with your repo's `typewriter.yml`. |
| 112 | +$ npx typewriter@7 |
| 113 | +``` |
| 114 | + |
| 115 | +## API Token Configuration |
| 116 | + |
| 117 | +Typewriter requires a Segment API token to fetch Tracking Plans from the [Segment Config API](/docs/config-api/). |
| 118 | + |
| 119 | +You must be a workspace owner to create Segment API tokens. |
| 120 | + |
| 121 | +To create an API token: |
| 122 | +1. Click on the **Tokens** tab on the [Access Management](https://app.segment.com/goto-my-workspace/settings/access-management) page and click **Create Token**. |
| 123 | +2. Choose Segment's Config API. |
| 124 | +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. |
| 125 | +4. Click **Create**. |
| 126 | + |
| 127 | +Typewriter looks for an API token in three ways, in the following order: |
| 128 | +1. If a token is piped through, it will use that token. For example, `echo $TW_TOKEN | typewriter build`. |
| 129 | +2. Typewriter executes a token script from the `typewriter.yml`. See [Token Script](/docs/protocols/apis-and-extensions/typewriter/#token-script){:target="_blank"} for more information. |
| 130 | +3. Typewriter reads the contents of the `~/.typewriter` file. |
| 131 | + |
| 132 | +The quickstart wizard prompts you for an API token and stores it in `~/.typewriter` for you. |
| 133 | + |
| 134 | +Segment recommends you use a [Token Script](/docs/protocols/apis-and-extensions/typewriter/#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. |
| 135 | + |
| 136 | +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. |
0 commit comments