Getting started overview

Segment specializes in collecting, cleaning, and activating customer data from various sources into a unified platform. This guide outlines the initial steps required to begin using Segment, focusing on account setup, credential acquisition, and making a first successful data collection request. Users will typically create a Segment account, configure a data source, and then integrate a Segment SDK into their application or website to send event data. The process culminates in verifying that data is flowing into the Segment workspace, enabling subsequent transformations and routing to downstream destinations.

For a detailed understanding of Segment's architecture and capabilities beyond initial setup, consult the official Segment documentation portal.

Quick start table

Step What to do Where
1. Sign Up Create a new Segment account. Segment homepage
2. Create Workspace Set up your initial data workspace. Segment app UI after signup
3. Add Source Configure a new data source (e.g., JavaScript Website, Node.js). Segment app UI > Connections > Sources
4. Get Write Key Locate and copy the unique Write Key for your source. Segment app UI > Sources > [Your Source] > Settings
5. Install SDK Integrate the appropriate Segment SDK into your application. Your application codebase
6. Make First Call Implement an identify or track call. Your application codebase
7. Verify Data Check the debugger for incoming events. Segment app UI > Connections > Sources > [Your Source] > Debugger

Create an account and get keys

  1. Sign up for a Segment account: Navigate to the Segment website and complete the account registration process. Segment offers a free tier that supports up to 1,000 monthly tracked users (MTUs) and 2 sources, which is suitable for initial testing and prototyping.
  2. Create a Workspace: Upon successful signup, you will be prompted to create your first workspace. A workspace is a hierarchical container for all your Segment data, sources, destinations, and settings.
  3. Add a Source: Within your new workspace, go to the 'Connections' section and select 'Sources'. Click 'Add Source' and choose the type of source that matches your data collection environment. Common choices include:
    • JavaScript (Web): For websites and web applications.
    • Node.js (Server): For server-side applications.
    • iOS/Android (Mobile): For native mobile applications.
    • HTTP API (Server): For direct API calls from any environment.
  4. Configure your Source: Provide a name for your source. Segment will then display instructions specific to your chosen source type, including how to install the relevant SDK.
  5. Retrieve the Write Key: Once your source is created, navigate to its settings within the Segment UI. The 'Overview' or 'Settings' tab for your source will display a unique alphanumeric string known as the Write Key (sometimes referred to as the Source Write Key). This key is essential for authenticating your data calls to Segment and should be kept confidential, especially for server-side implementations.

Your first request

After obtaining your Write Key, the next step is to integrate a Segment SDK and send an initial data point. This example uses the Segment JavaScript SDK for a web application, but the general principles apply across other SDKs.

JavaScript SDK Installation (Analytics.js 2.0)

To integrate the JavaScript SDK into your website, embed the following snippet within the <head> tags of your HTML, replacing YOUR_WRITE_KEY with the Write Key you obtained:

<script>
  !function(){var analytics=window.analytics=window.analytics||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","page","identify","reset","group","track","ready","alias","debug","page","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware"];analytics.factory=function(e){return function(){var t=Array.prototype.slice.call(arguments);t.unshift(e);analytics.push(t);return analytics}};for(var e=0;e<analytics.methods.length;e++){var key=analytics.methods[e];analytics[key]=analytics.factory(key)}analytics.load=function(key,e){var t=document.createElement("script");t.type="text/javascript";t.async=!0;t.src="https://cdn.segment.com/analytics.js/v1/"+key+"/analytics.min.js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(t,n);analytics._writeKey=key;analytics.page();analytics.SNIPPET_VERSION="4.15.3"};analytics.SNIPPET_VERSION="4.15.3";
  analytics.load("YOUR_WRITE_KEY");
  analytics.page();
  }}
();
</script>

This snippet loads the Segment Analytics.js library asynchronously and initializes it with your Write Key. The analytics.page() call automatically tracks page views.

Sending an identify call

The identify call associates a user with a unique ID and optional traits. This is typically done after a user logs in or provides identifying information. Add the following JavaScript code to a location where you can access user data, for example, after a successful login:

analytics.identify('user-123', {
  name: 'John Doe',
  email: '[email protected]',
  plan: 'premium',
  createdAt: '2023-01-15T12:00:00Z'
});

Replace 'user-123' with a unique identifier for your user and populate the traits object with relevant information. More details on the identify method are available in the Segment Identify Method specification.

Sending a track call

The track call records specific actions users perform. This is fundamental for understanding user behavior. For instance, to track a 'Product Viewed' event:

analytics.track('Product Viewed', {
  productId: '507f1f77bcf86cd799439011',
  productName: 'Segment T-Shirt',
  category: 'Apparel',
  price: 29.99
});

Replace 'Product Viewed' with your event name and the properties with relevant data for that event. Refer to the Segment Track Method documentation for a comprehensive guide.

Verifying data flow

After implementing your first identify or track call, verify that the data is successfully reaching Segment:

  1. Go to your Segment workspace.
  2. Navigate to 'Connections' > 'Sources' and select the source you configured.
  3. Click on the 'Debugger' tab.
  4. Interact with your application/website (e.g., refresh the page, log in, perform the tracked action).
  5. You should see incoming events appear in the Debugger. Each event will display its type, properties, and the timestamp of collection.

Successful data ingestion in the debugger confirms that your Segment integration is working correctly.

Common next steps

Once your initial data collection is verified, consider these common next steps to expand your Segment implementation:

  • Add Destinations: Connect Segment to your downstream tools (e.g., analytics platforms, marketing automation systems, data warehouses). Segment supports hundreds of destination integrations.
  • Implement Additional Tracking: Expand your tracking plan to capture more significant user interactions and lifecycle events relevant to your business objectives.
  • Server-Side Tracking: For events that occur on your backend or require higher data integrity, implement server-side Segment SDKs (e.g., Node.js, Python, Ruby).
  • User and Group Management: Utilize group calls to associate individual users with companies or accounts, which is beneficial for B2B applications.
  • Data Governance with Protocols: For larger teams or regulated industries, Segment Protocols allows you to define and enforce a tracking plan, ensuring data quality and consistency. Learn more about Segment Protocols.
  • Audience Segmentation with Personas: Leverage Segment Personas to build unified user profiles and create targeted audience segments based on collected data for marketing and personalization efforts.
  • Security and Compliance: Review Segment's security features and ensure your data practices align with compliance requirements like GDPR or CCPA. For general information on data security best practices, consult resources like the Google Cloud security best practices guide, which covers principles applicable to cloud-based data platforms.

Troubleshooting the first call

If you encounter issues during your initial setup, consider the following troubleshooting steps:

  • Check Write Key: Ensure the Write Key in your SDK initialization code exactly matches the Write Key displayed in your Segment source settings. Typos are common.
  • Network Requests: Open your browser's developer tools (Network tab) and look for requests being sent to api.segment.io. A successful call will typically return a 200 OK status.
  • Ad Blockers/Browser Extensions: Some browser extensions (e.g., ad blockers, privacy tools) can prevent analytics scripts from loading or sending data. Temporarily disable them for testing.
  • SDK Load Order: For client-side SDKs, ensure the Segment snippet is loaded before any calls to analytics.identify() or analytics.track() are made. If calls are made before the SDK is fully initialized, they might be dropped or queued improperly.
  • Debugger Review: The Segment Debugger is the primary tool for real-time validation. If events are not appearing, check for any error messages or warnings within the Debugger itself.
  • Console Errors: Check your browser's JavaScript console for any errors related to the Segment SDK or your implementation.
  • CORS Issues: For server-side HTTP API calls, ensure your server is correctly handling Cross-Origin Resource Sharing (CORS) policies if the request originates from a different domain.
  • API Reference: Consult the Segment API reference for specific requirements on event structure and common error codes.