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/connections/sources/catalog/libraries/website/javascript/quickstart.md
+77-42Lines changed: 77 additions & 42 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,70 +4,109 @@ hidden: true
4
4
strat: ajs
5
5
---
6
6
7
-
This tutorial gets you started sending data from your website to Segment and any of our destinations, using Segment's Analytics.js library. As soon as you're set up you can turn on new destinations with the flip of a switch!
7
+
This tutorial gets you started sending data from your website to Segment and any of Segment's destinations, using Segment's Analytics.js library.
8
8
9
9
Want to learn more? Check out the [Analytics.js reference](/docs/connections/sources/catalog/libraries/website/javascript/).
10
10
11
-
## Step 1: Create a Source in the Segment app
11
+
## Step 1: Create a source in the Segment app
12
12
13
-
Before you begin, you need a Workspace (which is a container that holds all of the Sources and Destinations that are billed together for an organization). If you already created one, great! If not, you can sign up for a free Segment account and create one.
14
-
15
-
Next create an Analytics.js source from your Workspace:
13
+
Before you begin, you need a Workspace (which is a container that holds all of the Sources and Destinations that are billed together for an organization). You can sign up for a free Segment account and create a workspace.
16
14
15
+
To create an Analytics.js source source in the Segment app:
17
16
1. Click **Add Source**.
18
17
2. From the source catalog page, click **JavaScript**.
19
18
3. Click **Add Source** again from the informational panel that appears to the right.
20
19
4. Give the source a display name, and enter the URL the source will collect data from.
21
20
22
-
When you create a Source in the Segment web app, it tells the Segment servers that you'll be sending data from a specific source type. When you create (or change!) a Source in the Segment app, Segment generates a new Write Key for that source. You use the write key in your website code to tell Segment servers where the data is coming from, so Segment can route it to your Destinations and other tools.
21
+
When you create a source in the Segment web app, it tells the Segment servers that you'll be sending data from a specific source type. When you create (or change) a source in the Segment app, Segment generates a new write key for that source. You use the write key in your website code to tell Segment servers where the data is coming from, so Segment can route it to your Destinations and other tools.
22
+
23
+
24
+
## Step 2: Install Segment to your site
25
+
26
+
You can choose to install Segment to your site in 1 of 2 ways:
27
+
28
+
[a. Install Segment as a NPM package](#step-2a-install-segment-as-a-npm-package)
29
+
30
+
[b. Add the Segment snippet to your app](#step-2b-add-the-segment-snippet)
31
+
32
+
### Step 2a: Install Segment as a npm package
33
+
34
+
To install Segment as a npm package:
35
+
36
+
1. Install the analytics package.
37
+
38
+
```sh
39
+
# npm
40
+
npm install @segment/analytics-next
41
+
42
+
# yarn
43
+
yarn add @segment/analytics-next
23
44
45
+
# pnpm
46
+
pnpm add @segment/analytics-next
47
+
```
24
48
25
-
## Step 2: Add the Segment Snippet
49
+
2. Import and initialize the analytics.
26
50
27
-
> success "Install Segment as an NPM package"
28
-
> You can add Segment to your project as an [NPM package](https://www.npmjs.com/package/@segment/snippet){:target="_blank"}. For more information, see the instructions on [GitHub](https://github.com/segmentio/analytics-next#-using-as-an-npm-package){:target="_blank"}.
51
+
```js
52
+
import { AnalyticsBrowser } from '@segment/analytics-next'
29
53
30
-
Paste this snippet into the `<head>` tag of your site to install Segment.
Next, replace `YOUR_WRITE_KEY` in the snippet you pasted with your Segment project's **Write Key**. You can [find the write key](/docs/connections/find-writekey/) in your project set up guide or in the source's settings.
58
+
export const analytics = new AnalyticsBrowser()
59
+
analytics.load({ writeKey: 'YOUR_WRITE_KEY' })
60
+
```
35
61
36
-
> note ""
37
-
> **Note:** When you use Analytics.js in device-mode the source's Write Key is public, because it runs in a user's browser and can be accessed using the browser's developer tools. If this is not acceptable to your organization, you can explore [other Segment Sources](/docs/connections/sources/catalog/) which collect data from a server-based installation, and which are not accessible to the user.
62
+
For more initialization patterns and general information on `@segment/analytics-next`, see the repository's [README](https://github.com/segmentio/analytics-next/tree/master/packages/browser){:target="_blank"}.
38
63
39
-
That snippet loads Analytics.js onto the page _asynchronously_, so it won't affect your page load speed. Once the snippet is running on your site, you can turn on Destinations from the Destinations page in your workspace and they start loading on your site automatically.
64
+
### Step 2b: Add the Segment Snippet
65
+
66
+
To add the Segment snippet to your app:
67
+
68
+
Paste the snippet into the `<head>` tag of your site to install Segment.
69
+
70
+
{% include content/snippet-helper.md %}
71
+
72
+
Replace `YOUR_WRITE_KEY` in the snippet you pasted with your Segment project's **Write Key**. [Find the write key](/docs/connections/find-writekey/) in your project set up guide or in the source's settings.
73
+
74
+
> info ""
75
+
> When you use Analytics.js in device-mode, the source's Write Key is public, because it runs in a user's browser and can be accessed using the browser's developer tools. If this is not acceptable to your organization, you can explore [other Segment Sources](/docs/connections/sources/catalog/) which collect data from a server-based installation, and which are not accessible to the user.
76
+
77
+
That snippet loads Analytics.js onto the page _asynchronously_, so it won't affect your page load speed. Once the snippet is running on your site, you can turn on destinations from the destinations page in your workspace and they start loading on your site automatically.
40
78
41
79
Note that you should remove other native third-party destination code that you might have on your site. For example, if you're using Segment to send data to Google Analytics, make sure you remove the Google Analytics snippet from your site source code to prevent sending the data twice.
42
80
43
-
**Fun fact:** if you only want the most basic Google Analytics set up you can stop reading right now. You're done! Just switch on Google Analytics in our interface.
81
+
> info ""
82
+
> If you only want the most basic Google Analytics setup, there's no need to continue with the setup. Just toggle on Google Analytics in the Segment interface.
44
83
45
-
However, lots of analytics and marketing tools need to record _who_ each user is on your site. If you want to use any tool that deals with the identity of your users, read on about the `identify` method.
84
+
A lot of analytics and marketing tools need to record who each user is on your site. If you want to use any tool that deals with the identity of your users, read on about the Identify method.
46
85
47
-
## Step 3: Identify Users
86
+
## Step 3: Identify users
48
87
49
-
> note ""
50
-
> **Good to know**: For any of the different methods described in this quickstart, you can replace the properties and traits in the code samples with variables that represent the data collected.
88
+
> info ""
89
+
> For any of the different methods described in this quickstart, you can replace the properties and traits in the code samples with variables that represent the data collected.
51
90
52
-
The `identify` method is how you tell Segment who the current user is. It includes a unique User ID, and any optional traits you know about them. You can read more about it in the [identify method reference](/docs/connections/sources/catalog/libraries/website/javascript#identify).
91
+
The Identify method is how you tell Segment who the current user is. It includes a unique User ID, and any optional traits you know about them. You can read more about it in the [identify method reference](/docs/connections/sources/catalog/libraries/website/javascript#identify).
53
92
54
-
**Note:**You don't need to call `identify` for anonymous visitors to your site. Segment automatically assigns them an `anonymousId`, so just calling `page` and `track` works just fine without `identify`.
93
+
You don't need to call Identifyfor anonymous visitors to your site. Segment automatically assigns them an `anonymousId`, so just calling `page` and `track` works just fine without Identify.
55
94
56
-
Here's what a basic call to `identify` might look like:
95
+
Here's what a basic call to Identify might look like:
57
96
58
97
```js
59
98
analytics.identify('f4ca124298', {
60
99
name: 'Michael Brown',
61
100
email: 'mbrown@example.com'
62
101
});
63
102
```
64
-
That identifies Michael by his unique User ID (in this case, `f4ca124298`, which is what you know him by in your database) and labels him with `name` and `email` traits.
103
+
This identifies Michael by his unique User ID (in this case, `f4ca124298`, which is what you know him by in your database) and labels him with `name` and `email` traits.
65
104
66
-
**Hold up though!**When you actually put that code on your site, you need to replace those hard-coded trait values with the variables that represent the details of the currently logged-in user.
105
+
When you actually put that code on your site, you need to replace those hard-coded trait values with the variables that represent the details of the currently logged-in user.
67
106
68
-
To do that, we recommend that you use a backend template to inject an `identify` call into the footer of **every page** of your site where the user is logged in. That way, no matter what page the user first lands on, they will always be identified. You don't need to call `identify` if your unique identifier (`userId`) is not known.
107
+
To do that, Segment recommends that you use a backend template to inject an Identify call into the footer of every page of your site where the user is logged in. That way, no matter what page the user first lands on, they will always be identified. You don't need to call Identifyif your unique identifier (`userId`) is not known.
69
108
70
-
Depending on your templating language, your actual `identify` call might look something like this:
109
+
Depending on your templating language, your actual Identify call might look something like this:
With that call in your page footer, you successfully identify every user that visits your site.
82
121
83
-
**Second fun fact:** if you only want to use a basic CRM set up, you can stop here. Just enable Salesforce, Intercom, or any other CRM system from your Segment workspace, and Segment starts sending all of your user data to it!
122
+
If you only want to use a basic CRM setup, you can stop here. Just enable Salesforce, Intercom, or any other CRM system from your Segment workspace, and Segment starts sending all of your user data to it.
84
123
85
-
Of course, lots of analytics tools record more than just _identities_... they record the actions each user performs too! If you're looking for a complete event tracking analytics setup, keep reading...
124
+
A lot of analytics tools record more than just _identities_ as they record the actions each user performs too. If you're looking for a complete event tracking analytics setup, keep reading...
86
125
87
126
88
-
## Step 4: Track Actions
127
+
## Step 4: Track actions
89
128
90
-
The `track` method is how you tell Segment about the actions your users are performing on your site. Every action triggers what we call an "event", which can also have associated properties. You can read more about `track` in the [track method reference](/docs/connections/sources/catalog/libraries/website/javascript#track).
129
+
The Track method is how you tell Segment about the actions your users are performing on your site. Every action triggers what's called an "event", which can also have associated properties. You can read more about Trackin the [track method reference](/docs/connections/sources/catalog/libraries/website/javascript#track).
91
130
92
-
Here's what a call to `track` call might look like when a user signs up:
131
+
Here's what a call to a Track call might look like when a user signs up:
93
132
94
133
```js
95
134
analytics.track('Signed Up', {
96
135
plan: 'Enterprise'
97
136
});
98
137
```
99
138
100
-
That tells us that your user triggered the **Signed Up** event, and chose your hypothetical `'Enterprise'` plan. Properties can be anything you want to record, for example:
139
+
That tells Segment that your user triggered the `Signed Up` event, and chose your hypothetical `'Enterprise'` plan. Properties can be anything you want to record, for example:
If you're just getting started, some of the events you should track are events that indicate the success of your site, like **Signed Up**, **Item Purchased** or **Article Bookmarked**.
111
150
112
-
To get started, we recommend that you track just a few important events. You can always add more later!
113
-
114
-
Once you add a few `track` calls, **you're done with this tutorial!** You successfully installed Analytics.js tracking. Now you're ready to turn on any Destination you like from our interface, margarita in hand.
115
-
116
-
117
-
---
151
+
To get started, Segment recommends that you track just a few important events. You can always add more later.
118
152
153
+
After you add a few Track calls, you successfully installed Analytics.js tracking. Now you're ready to turn on any destination you like from the Segment interface.
119
154
120
-
## What's Next?
155
+
## What's next?
121
156
122
-
We just walked through the quickest way to get started with Segment using Analytics.js. You might also want to check out our full [Analytics.js reference](/docs/connections/sources/catalog/libraries/website/javascript) to see what else is possible, or read about the [Tracking API methods](/docs/connections/sources/catalog/libraries/server/http/) to get a sense for the bigger picture.
157
+
You might want to check out the full [Analytics.js reference](/docs/connections/sources/catalog/libraries/website/javascript) to see what else is possible, or read about the [Tracking API methods](/docs/connections/sources/catalog/libraries/server/http/) to get a sense for the bigger picture.
123
158
124
-
If you're running an **Ecommerce** site or app you should also check out our [Ecommerce API reference](/docs/connections/spec/ecommerce/v2/) to make sure your products and checkout experience are instrumented properly!
159
+
If you're running an ecommerce site or app you should also check out Segment's [ecommerce API reference](/docs/connections/spec/ecommerce/v2/) to make sure your products and checkout experience are instrumented properly.
0 commit comments