diff --git a/src/getting-started/02-simple-install.md b/src/getting-started/02-simple-install.md index c4bf93f93e..8cb42d55e3 100644 --- a/src/getting-started/02-simple-install.md +++ b/src/getting-started/02-simple-install.md @@ -2,28 +2,26 @@ title: A Basic Segment Installation --- - When you implement Segment, you add Segment code to your website, app, or server. This code generates messages based on specific triggers you define. - -In a basic implementation, the code can be a snippet of JavaScript that you copy and paste into the HTML of a website to track page views. It can also be as complex as Segment calls embedded in a React mobile app to send messages when the app is opened or closed, when the user performs different actions, or when time based conditions are met (for example "ticket reservation expired" or "cart abandoned after 2 hours"). +In a basic implementation, the code can be a snippet of JavaScript that you copy and paste into the HTML of a website to track page views. It can also be as complex as Segment calls embedded in a React mobile app to send messages when the app is opened or closed, when the user performs different actions, or when time based conditions are met, for example "ticket reservation expired" or "cart abandoned after 2 hours". The best way to learn about how Segment works is to see it in action. This tutorial walks you through an installation using one of Segment's libraries: JavaScript, PHP, or the iOS library. -## Before you begin +## Prerequisites Before you start your Segment implementation, you need: 1. A Segment user account and a workspace. If you're not already part of an organization with a Segment Workspace, you can [sign up for a free account and workspace](https://app.segment.com/signup/?ref=docs). 2. Access to the code for a basic website, PHP website, or an iOS app. > success "" -> **Tip**! If you don't have any of those things, consider creating a simple [GitHub Pages website](https://pages.github.com/). +> If you don't have any of those things, consider creating a simple [GitHub Pages website](https://pages.github.com/). ### Create separate dev and prod sources -When you develop and test sources, Segment recommends you to create and use separate sources for each of your environments (production, development, staging) to prevent testing and development activities from filling production systems with invalid data. +When you develop and test sources, we recommend you create and use separate sources for each of your environments (production, development, staging) to prevent testing and development activities from filling production systems with invalid data. -You can give each source an environment label when you create it, and Segment strongly suggests that you use these labels to sort your sources. When you create a source during the steps below, make sure you enter an environment label. +You can give each source an environment label when you create it, and we strongly suggest that you use these labels to sort your sources. When you create a source during the steps below, make sure you enter an environment label. > warning "" > Double-check when you enter write keys for dev and production environments to make sure that you send the right data to the right place. @@ -35,8 +33,8 @@ To create a Segment source: 1. Go to your Segment workspace, and navigate to [the Sources catalog](https://app.segment.com/goto-my-workspace/sources/catalog). 2. Select your source. You can choose from either the [Javascript source](https://app.segment.com/goto-my-workspace/sources/catalog/javascript), the [PHP source](https://app.segment.com/goto-my-workspace/sources/catalog/php), or the [iOS source](https://app.segment.com/goto-my-workspace/sources/catalog/ios). 3. Click **Add Source**. -4. Enter a name for the source. Segment recommends that you include the word `demo`, `test`, or `quickstart` in the name so you can easily find and delete this source later. -5. *(Optional)* Add an Environment label of `dev` to the source in the **Labels** field. Segment recommends you do this so that you know this demo source isn't part of a production installation. +4. Enter a name for the source. We recommend that you include the word `demo`, `test`, or `quickstart` in the name so you can easily find and delete this source later. +5. *(Optional)* Add an Environment label of `dev` to the source in the **Labels** field. We recommend you do this so that you know this demo source isn't part of a production installation. 6. *(Optional)* Add the website URL. Segment provides this field so that you can flag the website being tracked to the source. Segment does not use this URL anywhere else. ## Find your write key @@ -47,20 +45,20 @@ To find your write key: 1. Go to **Connections > Sources** and select your source. 2. Click the **Settings** tab for the source and click **API Keys**. -Make note of or write down your write key, as you'll need it in the next steps. +Make note of the write key, as you'll need it in the next steps. Any time you change a library's settings in the Segment App, the write key regenerates. ![Screenshot of a source's settings page, with the API Keys tab selected.](/docs/connections/images/find_writekey.png) > info "" -> [Cloud-sources](/docs/connections/sources/about-cloud-sources/) do not have write keys, as they use a token or key from your account with that service. Cloud-sources have other considerations and aren't part of this tutorial. +> [Cloud-sources](/docs/connections/sources/about-cloud-sources/) do not have write keys as they use a token or key from your account with that service. Cloud-sources have other considerations and aren't part of this tutorial. ## Installing Segment -Click a tab below to see the tutorial content for the specific library you chose. +Click a tab to see the tutorial content for the specific library you chose. {% codeexample %} {% codeexampletab Javascript quickstart %} @@ -68,7 +66,7 @@ Click a tab below to see the tutorial content for the specific library you chose -### Step 1: Copy the Snippet +### Step 1: Copy the snippet
Navigate to **Connections > Sources > JavaScript** in the Segment app, copy the snippet from the JavaScript Source overview page, and paste it into the `` tag of your site.

@@ -76,16 +74,17 @@ That snippet loads Analytics.js onto the page _asynchronously_, so it won't affe

> info "" -> The Segment snippet version history available on [GitHub](https://github.com/segmentio/snippet/blob/master/History.md){:target="_blank"}. Segment recommends that you use the latest snippet version whenever possible. +> The Segment snippet version history available on [GitHub](https://github.com/segmentio/snippet/blob/master/History.md){:target="_blank"}. We recommend that you use the latest snippet version whenever possible.
-### Step 2: Identify Users + +### Step 2: Identify users
-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). +The [Identify](/docs/connections/spec/identify/) method tells 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).

> info "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`. -

+> Segment automatically assigns them an `anonymousId` so just calling `page` and `track` works without `identify`. +
Here's an example of what a basic call to `identify` might look like: ```js @@ -95,9 +94,9 @@ analytics.identify('f4ca124298', { }); ```
-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. When you 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. +This identifies Michael by his unique userId, in this case, _`f4ca124298`_, which is what you know him by in your database. He is labelled with `name` and `email` traits. When you 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.

-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 `identify` if your unique identifier (`userId`) is not known. +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.

Depending on your templating language, your actual identify call might look something like this: @@ -116,9 +115,10 @@ With that call in your page footer, you successfully identify every user that vi > You've completed a basic CRM set up. Return to the Segment app to enable Salesforce, Intercom, or your CRM system of choice and Segment starts sending all of your user data to it.
-### Step 3: Track Actions + +### Step 3: Track actions
-The `track` method is how you tell Segment about the actions your users are performing on your site. Every action triggers what Segment calls 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). +The [Track](/docs/connections/spec/track) method tells Segment about the actions your users are performing on your site. Every action triggers 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).

Here's an example of what a call to `track` might look like when a user signs up: @@ -140,9 +140,9 @@ analytics.track('Article Bookmarked', { }); ```
-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**. Segment recommends that you track a few important events as you can always add more later. +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**. We recommend that you track a few important events as you can always add more later.

-Once you add a few `track` calls, you're done with setting up Segment. You successfully installed Analytics.js tracking. Now you're ready to turn on any destination you like from the Segment App. +Once you add a few Track calls, you're done with setting up Segment. You successfully installed Analytics.js tracking. Now you're ready to turn on any destination you like from the Segment App. @@ -158,7 +158,8 @@ Once you add a few `track` calls, you're done with setting up Segment. You succe ### Step 1: Install the SDK
-To install Analytics-iOS, Segment recommends you to use [CocoaPods](http://cocoapods.org){:target="_blank"}, because it allows you to create a build with specific bundled destinations, and because it makes it simple to install and upgrade. +To install Analytics-iOS, we recommend you to use [CocoaPods](http://cocoapods.org){:target="_blank"}, because it allows you to create a build with specific bundled destinations and it simplifies installation and upgrading. +

1) Add the `Analytics` dependency to your `Podfile` by adding the following line: @@ -176,7 +177,7 @@ configuration.recordScreenViews = YES; // Enable this to record screen views aut ```
> success "" -> You don't _need_ to use initialization config parameters to track lifecycle events (`Application Opened`, `Application Installed`, `Application Updated`) and screen views automatically, but Segment highly recommends that you do, so you can start off already tracking some important core events. +> You don't _need_ to use initialization config parameters to track lifecycle events (`Application Opened`, `Application Installed`, `Application Updated`) and screen views automatically, but we highly recommend that you do, so that you can start off already tracking some important core events.
3) Import the SDK in the files that you use it by adding the following line: @@ -185,18 +186,22 @@ configuration.recordScreenViews = YES; // Enable this to record screen views aut #import ```
-#### Bundling Client Side SDKs +#### Bundling client-side SDKs +
To keep the Segment SDK lightweight, the `Analytics` pod only installs the Segment library. This means all of the data goes first to Segment's servers, and is then forwarded to any destination tools which accept the data _from Segment_. -

+
+
Some destinations don't accept data from the Segment servers, and instead require that you collect the data from the device. In these cases you must bundle some additional destination code with the Segment SDK. This document skips over this part, but you can see the instructions on [how to bundle the destination tools](/docs/connections/sources/catalog/libraries/mobile/ios/#about-mobile-connection-modes). -

+
+
Now that the SDK is installed and set up, you're ready to start making calls.

-### Step 2: Identify Users -
-The `identify` method is how you tell Segment who the current user is. It takes a unique User ID, and any optional traits you know about them. You can read more about it in the [identify reference](/docs/connections/sources/catalog/libraries/mobile/ios#identify). + +### Step 2: Identify users
+The [Identify](/docs/connections/spec/identify/) method tells Segment who the current user is. It takes a unique user ID and any optional traits you know about them. You can read more about it in the [Identify reference](/docs/connections/sources/catalog/libraries/mobile/ios#identify). +

Here's an example of what a basic call to `identify` might look like: ```objc @@ -205,15 +210,17 @@ Here's an example of what a basic call to `identify` might look like: @"email": @"mbrown@example.com" }]; ```
-This call identifies Michael by his unique User ID (`f4ca124298`, which is the one you know him by in your database) and labels him with `name` and `email` traits. +This call identifies Michael by his unique user ID, `f4ca124298`, which is the one you know him by in your database, and labels him with `name` and `email` traits.

> info "" -> When you put the above code in your iOS app, you would replace those hard-coded trait values with variables that represent the details of the user that's currently signed in. -

-### Step 3: Track Actions +> When you put the code in your iOS app, replace the hard-coded trait values with variables that represent the details of the user that's currently signed in.
-The `track` method is how you tell Segment about the actions your users are performing in your app. 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/mobile/ios#track). +### Step 3: Track actions +
+The [Track](/docs/connections/spec/track) method tells Segment about the actions your users are performing in your app. Every action triggers an "event", which can also have associated properties. You can read more about `track` in the [Track method reference](/docs/connections/sources/catalog/libraries/mobile/ios#track). +
+
The Segment iOS SDK can automatically track a few important common events, such as **Application Installed**, **Application Updated**, and **Application Opened**. You can enable this option during initialization by adding the following lines: ```objc @@ -224,14 +231,14 @@ configuration.trackApplicationLifecycleEvents = YES;
You should also track events that indicate success in your mobile app, like **Signed Up**, **Item Purchased**, or **Article Bookmarked**. Segment recommends that you track a few important events as you can always add more later.

-Here's what a `track` call might look like when a user signs up: +Here's what a Track call might look like when a user signs up: ```objc [[SEGAnalytics sharedAnalytics] track:@"Signed Up" properties:@{ @"plan": @"Enterprise" }]; ```
-This tells us that your user triggered the **Signed Up** event, and chose your hypothetical `'Enterprise'` plan. +This 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: @@ -243,7 +250,7 @@ Properties can be anything you want to record, for example: @"author": @"John Branch" }]; ```
-Once you've added a few `track` calls, you're all set. You successfully instrumented your app, and can enable destinations from your Segment workspace. +Once you've added a few Track calls, you're all set. You successfully instrumented your app, and can enable destinations from your Segment workspace. @@ -259,7 +266,7 @@ Once you've added a few `track` calls, you're all set. You successfully instrume
To install the library:

-1) Clone the repository from GitHub into your desired application directory. (If you're a composer user, [you can use this](https://packagist.org/packages/segmentio/analytics-php).) +1) Clone the repository from GitHub into your desired application directory. If you're a Composer user, see the [Segment PHP Analystics package](https://packagist.org/packages/segmentio/analytics-php){:target="_blank"}. ```bash git clone https://github.com/segmentio/analytics-php /my/application/folders/ @@ -272,7 +279,7 @@ require_once("/path/to/analytics-php/lib/Segment.php"); use Segment\Segment; ```
-3) In your initialization script, make the following call (In the example, Segment first renames this module to `Analytics` for convenience): +3) In your initialization script, make the following call. In the example, Segment first renames this module to `Analytics` for convenience: ```php # Set up our Segment tracking and @@ -281,20 +288,21 @@ class_alias('Segment', 'Analytics'); Segment::init("YOUR_WRITE_KEY"); ```
-4) Replace `YOUR_WRITE_KEY` with the actual write key, which you can find in Segment under your project settings. Otherwise, all that data goes straight to `/dev/null`. +4) Replace _`YOUR_WRITE_KEY`_ with the actual write key, which you can find in Segment under your project settings. Otherwise, all that data goes straight to `/dev/null`.

-You only need to call `init` once when your php file is requested. All of your files then have access to the same `Analytics` client. - - +You only need to call `init` once when your PHP file is requested. All of your files then have access to the same `Analytics` client. +
+
> info "" -> Segment's default PHP consumer is the [libcurl consumer](/docs/connections/sources/catalog/libraries/server/php/#lib-curl-consumer). If this is not working well for you or if you have a high-volume project, you might try one of Segment's other consumers like the [fork-curl consumer](/docs/connections/sources/catalog/libraries/server/php/#fork-curl-consumer). +> Segment's default PHP consumer is the [libcurl consumer](/docs/connections/sources/catalog/libraries/server/php/#lib-curl-consumer). If this is not working well for you or if you have a high-volume project, try one of Segment's other consumers like the [fork-curl consumer](/docs/connections/sources/catalog/libraries/server/php/#fork-curl-consumer).
-### Step 2: Identify Users + +### Step 2: Identify users
-The [`identify`](/docs/connections/spec/identify) method is how you tell Segment who the current user is. It includes a unique User ID and any optional traits that you might know about them. +The [Identify](/docs/connections/spec/identify) method tells Segment who the current user is. It includes a unique user ID and any optional traits that you might know about them.

-Here's what a basic call to [`identify`](/docs/connections/spec/identify) might look like: +Here's what a basic call to `identify` might look like: ```php Segment::identify(array( @@ -306,11 +314,12 @@ Segment::identify(array( )); ```
-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. - +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. +
+
> info "" -> 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. The easiest way in PHP is to keep a `$user` variable in memory. - +> When you put that code on your site, replace the hard-coded trait values with the variables that represent the details of the currently logged-in user. We recommend you keep a `$user` variable in memory. +
```php Segment::identify(array( "userId" => $user->id, @@ -323,14 +332,15 @@ Segment::identify(array(
With that call on the page, you're now identifying every user that visits your site.

-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. +If you only want to use a basic CRM set up, you can stop here. Enable Salesforce, Intercom, or any other CRM system from your Segment workspace, and Segment starts sending all of your user data to it.
-### Step 3: Track Actions + +### Step 3: Track actions
-The `track` method is how you tell Segment about the actions your users are performing on your site. Every action triggers what Segment calls an "event", which can also have associated properties. +The [Track](/docs/connections/spec/track/) method tells Segment about the actions your users are performing on your site. Every action triggers an "event", which can also have associated properties.

-Here's what a call to [`track`](/docs/connections/spec/track/) might look like when a user signs up: +Here's what a call to `track` might look like when a user signs up: ```php Segment::track(array( @@ -360,18 +370,20 @@ Segment::track(array(
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**.

-To get started, Segment recommends you to track track a few important events as you can always add more later. +To get started, we recommend you track a few important events as you can always add more later.
+ ### Step 4: Flush the data
-Call the Segment `flush()` method. This manually sends all the queued call data to make sure it makes it to the Segment servers. This is normally done automatically by the runtime, but some PHP installations won't do it for you, so it's worth calling at the end of your script, just to be safe. +Call the Flush method. This manually sends all the queued call data to make sure it makes it to the Segment servers. This is normally done automatically by the runtime, but some PHP installations won't do it for you. +

```php Segment::flush(); ``` - -You've successfully installed PHP tracking. Now you're ready to turn on any destination from the Segment App. +
+You've now installed PHP tracking and you're ready to turn on any destination from the Segment App. @@ -379,7 +391,6 @@ You've successfully installed PHP tracking. Now you're ready to turn on any dest {% endcodeexample %} - ## Test that it's working Once you've set up your Segment library, and instrumented at least one call, you can look at the Debugger tab for the Source to check that it produces data as you expected. @@ -391,7 +402,7 @@ The Source Debugger is a real-time tool that helps you confirm that API calls ma The Debugger is separate from your workspace's data pipeline, and is not an exhaustive view of all the events ever sent to your Segment workspace. The Debugger only shows a sample of the events that the Source receives in real time, with a cap of 500 events. The Debugger is a great way to test specific parts of your implementation to validate that events are being fired successfully and arriving to your Source. > success "" -> **Tip**: To see a more complete view of all your events, you might consider setting up either a [warehouse](/docs/connections/storage/warehouses/) or an [S3 destination](/docs/connections/storage/catalog/amazon-s3/). +> To see a more complete view of all your events, consider setting up either a [warehouse](/docs/connections/storage/warehouses/) or an [S3 destination](/docs/connections/storage/catalog/amazon-s3/). The Debugger shows a live stream of sampled events arriving at the Source, but you can also toggle from "Live" to "Pause" to stop the stream and prevent it from displaying new events. Events continue to arrive to your Source while you Pause the stream, they just are not displayed. @@ -407,15 +418,15 @@ Two views are available when viewing a payload: ## Set up your first destination -Once you're satisfied that data is arriving from your new source, it's time to set up your first destination! As long as you have `page` or `screen` data coming from the source, you can quickly enable Google Analytics to look at the page view statistics. +Once you're satisfied that data is arriving from your new source, it's time to set up your first destination. As long as you have `page` or `screen` data coming from the source, you can enable Google Analytics to look at the page view statistics. If you don't have a Google Analytics account, you can either set up a free account, or look at the Destination Catalog for a different destination to enable. -You'll need a tracking ID for Google Analytics (either a "website" or "serverside" tracking ID), or another API key if you're substituting another destination. Make a note of this ID or key as you'll need it to connect your destination. +You need a tracking ID for Google Analytics (either a "website" or "serverside" tracking ID), or another API key if you're substituting another destination. Make a note of this ID or key as you need it to connect your destination. To set up your first destination: -1. Go to your Segment workspace, click **Destinations**, and click **Add Destination** to go to the [Catalog](https://app.segment.com/goto-my-workspace/destinations/catalog). +1. Go to your Segment workspace, click **Destinations**, and click **Add Destination** to go to the [Catalog](https://app.segment.com/goto-my-workspace/destinations/catalog){:target="_blank"}. 2. Search for the destination you want to add. In this case, search for `Google Analytics`. 3. Click the tile for the destination to see information about it. 4. Click **Configure Google Analytics**. @@ -426,12 +437,12 @@ To set up your first destination: -Congratulations! Data is now flowing from the source you set up, to the first destination. Do some test browsing on your site or app, then log in to your downstream tool to see the data in place. +Data is now flowing from the source you set up, to the first destination. Do some test browsing on your site or app, then log in to your downstream tool to see the data in place. You can click around and load pages to see your Segment calls in action, watch them arrive in the Debugger, and see them arrive in the destination tool. > warning "" -> **Note:** When you're done with this test source and destination, you can delete them. This prevents you from getting unplanned "demo" data in your production environment later. +> **Note**: When you're done with this test source and destination, you can delete them. This prevents you from getting unplanned "demo" data in your production environment later.