Skip to content

Commit 41fa695

Browse files
bot-docsteambot-docsteam
authored
Merge pull request #519 from segmentio/repo-sync
repo sync
2 parents 06404a9 + 9d34ae8 commit 41fa695

File tree

2 files changed

+336
-163
lines changed

2 files changed

+336
-163
lines changed

‎src/protocols/apis-and-extensions/typewriter-v7.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: 'Typewriter v7'
3+
hidden: true
4+
---
5+
6+
Analytics-iOS and Analytics-Android support Typewriter v7. 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 with [Node.js](https://nodejs.org/en/), and requires `[email protected]` or later, and `[email protected]` or later.
11+
12+
Run the following commands to verify your installed versions of Node and NPM:
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, [install `node`](https://nodejs.org/en/download/package-manager). Installing `node` also installs the`npm` and `npx` package managers . 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){:target="_blank"} 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 allows you to keep your token secret, but it also allows you to share it across your team.

0 commit comments

Comments
 (0)