When you implement Segment, you add Segment code to your website, app, or server. This code generates messages based on specific triggers you define. Show
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 though an installation using one of Segment’s libraries: JavaScript, PHP, or the iOS library. Before you beginBefore you start your Segment implementation, you need:
Create separate dev and prod sourcesWhen 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. 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. 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. Create a Segment sourceTo create a Segment source:
Find your write keyThe write key is the unique identifier for a source that tells Segment which source data comes from, to which workspace the data belongs, and which destinations should receive the data. To find your write key:
Make note of or write down your 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. Installing SegmentClick a tab below to see the tutorial content for the specific library you chose.
That snippet loads Analytics.js onto the page asynchronously, so it won’t affect your page load speed. Once the snippet runs on your site, you can turn on destinations from the destinations page in your workspace and data starts loading on your site automatically. Note: If you only want the most basic Google Analytics setup you can stop reading right now. You’re done! Just toggle on Google Analytics from the Segment App. Step 2: Identify Users
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. Here’s an example of what a basic call to identify might look like: analytics.identify('f4ca124298', { name: 'Michael Brown', email: '' });
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. Depending on your templating language, your actual identify call might look something like this: analytics.identify(' {{user.id}} ', { name: '{{user.fullname}}', email: '{{user.email}}' }); With that call in your page footer, you successfully identify every user that visits your site. Note: 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. Step 3: Track Actions
Here’s an example of what a call to track might look like when a user signs up: analytics.track('Signed Up', { plan: 'Enterprise' });
Properties can be anything you want to record, for example: analytics.track('Article Bookmarked', { title: 'Snow Fall', subtitle: 'The Avalanche at Tunnel Creek', author: 'John Branch' });
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.
pod 'Analytics', '~> 3.0'
SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration configurationWithWriteKey:@"YOUR_WRITE_KEY"]; configuration.trackApplicationLifecycleEvents = YES; // Enable this to record certain application events automatically! configuration.recordScreenViews = YES; // Enable this to record screen views automatically! [SEGAnalytics setupWithConfiguration:configuration]; 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.
#import <Analytics/SEGAnalytics.h> 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. Now that the SDK is installed and set up, you’re ready to start making calls.Step 2: Identify Users
[[SEGAnalytics sharedAnalytics] identify:@"f4ca124298" traits:@{ @"name": @"Michael Brown", @"email": @"" }];
Note: When you put that code in your iOS app, you need to replace those hard-coded trait values with the variables that represent the details of the currently logged-in user. Step 3: Track Actions
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: SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration configurationWithWriteKey:@"YOUR_WRITE_KEY"]; configuration.trackApplicationLifecycleEvents = YES; [SEGAnalytics setupWithConfiguration:configuration];
Here’s what a track call might look like when a user signs up: [[SEGAnalytics sharedAnalytics] track:@"Signed Up" properties:@{ @"plan": @"Enterprise" }];
Properties can be anything you want to record, for example: [[SEGAnalytics sharedAnalytics] track:@"Article Bookmarked" properties:@{ @"title": @"Snow Fall", @"subtitle": @"The Avalanche at Tunnel Creek", @"author": @"John Branch" }];
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.) git clone https://github.com/segmentio/analytics-php /my/application/folders/
require_once("/path/to/analytics-php/lib/Segment.php"); use Segment\Segment;
# Set up our Segment tracking and # alias to Analytics for convenience class_alias('Segment', 'Analytics'); Segment::init("YOUR_WRITE_KEY");
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. Note: The default PHP consumer is the libcurl 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. Step 2: Identify Users
Here’s what a basic call to identify might look like: Segment::identify(array( "userId" => "f4ca124298", "traits" => array( "name" => "Michael Brown", "email" => "" ) ));
Note: 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. Segment::identify(array( "userId" => $user->id, "traits" => array( "name" => $user->fullname, "email" => $user->email ) )); 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. Step 3: Track Actions
Here’s what a call to track might look like when a user signs up: Segment::track(array( "userId" => "f4ca124298", "event" => "Signed Up", "properties" => array( "plan" => "Enterprise" ) ));
Properties can be anything you want to record, for example: Segment::track(array( "userId" => "f4ca124298", "event" => "Article Bookmarked", "properties" => array( "title" => "Snow Fall", "subtitle" => "The Avalanche at Tunnel Creek", "author" => "John Branch" ) ));
To get started, Segment recommends you to track track a few important events as you can always add more later. Step 4: Flush the data
You’ve successfully installed PHP tracking. Now you’re ready to turn on any destination from the Segment App. Test that it’s workingOnce 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. The Source Debugger is a real-time tool that helps you confirm that API calls made from your website, mobile app, or servers arrive at your Segment Source, so you can quickly see how calls are received by your Segment source, so you can troubleshoot quickly without having to wait for data processing. 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. Tip: To see a more complete view of all your events, you might consider setting up either a warehouse or an S3 destination. The Debugger shows a live stream of sampled events arriving at the Source, but you can also toggled 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. You can search on any information you know is available in an event payload to search in the Debugger and show only matching payloads. You can also use advanced search options to limit the results to a specific event. Two views are available when viewing a payload:
Set up your first destinationOnce 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. 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 note of this ID or key as you’ll need it to connect your destination. 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. 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. 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. This page was last modified: 09 Aug 2022 |