Skip to Content

Connecting Segment CDP to Usermaven

Integrate your Segment data with Usermaven to get a complete view of your customer journey. By adding Usermaven as a Destination in your Segment workspace, you can instantly start sending valuable event data from your existing sources (like your website, mobile app, and servers) directly into your Usermaven analytics environment.

This integration allows you to leverage your existing Segment setup to power Usermaven, simplifying your event tracking implementation.

Important: Choosing your integration approach

There are two ways to use this integration. Choosing the right one is critical for getting the data you need.

Option A: Segment-only approach (for product analytics)

You can use Segment as your only tracking library. This is a simple setup ideal for analyzing in-app product activity or server-to-server events.

Limitation: With this approach, Usermaven does not have access to the rich browser context (like UTM parameters, referrers, and device details) that our own tracking pixel provides. This means it will not work well for marketing attribution or analyzing the top-of-funnel user journey.

Option B: Hybrid approach (recommended for complete analytics)

Use both the Usermaven pixel on your website and the Segment integration for your in-app and server-side events.

This is the best-of-both-worlds solution. The Usermaven pixel will handle marketing attribution and anonymous user tracking on your site, while Segment provides a convenient way to send events from your application’s backend or other cloud sources. The guide below will show you how to stitch this data together.

How the data flows

Regardless of your approach, the data flows in one direction: from your apps, through Segment, and into Usermaven.

Your Apps & Servers → Segment (as a data hub) → Usermaven (as a destination)

Basic setup: Connecting the Segment destination

This first step is required for both the Segment-only and hybrid approaches.

Step 1: Find your Usermaven API key

  1. Log in to your Usermaven account.
  2. Navigate to Workspace Settings > Setup.
  3. Select the Segment tab.
  4. Copy your API Key. You will need this in a moment.

Step 2: Add the Usermaven destination in Segment

  1. Log in to your Segment workspace and navigate to the Catalog tab.
  2. Click on Destinations.
  3. Search for Usermaven and select it from the catalog.
  4. Click Configure Usermaven.
  5. Select the Segment Source you want to connect to Usermaven and click Next.
  6. Give your Destination a name (e.g., “Usermaven Production”) and click Create Destination.
  7. Once created, navigate to the Settings tab for the Usermaven destination and paste your API Key from Step 1 into the “API Key” field.
  8. Enable the destination by toggling the switch at the top.

Your setup is complete. For a Segment-only approach, you are done. If you want to enable full attribution with the recommended hybrid approach, continue to the next section.

Advanced setup: Configuring for full attribution (hybrid approach)

To get a complete picture of the user journey, it’s crucial that server-side events sent to Segment can be connected to the user activity tracked by the Usermaven pixel on your website.

There are two methods to achieve this.

This is the cleanest and most robust method. It leverages each tool for its primary strength.

The flow works like this:

  1. The Usermaven pixel, installed on your site, tracks all anonymous visitor activity.
  2. When a user signs up or logs in, you make a single usermaven.identify() call from your frontend code. Our pixel automatically handles the stitching of their anonymous history to their known user profile.
  3. For all subsequent events, your backend can now send events to Segment using the stable userId (e.g., their email or database ID). You no longer need to worry about the anonymousId.
  4. Segment forwards the server-side event to Usermaven, and we match it to the correct user profile using the userId.

Benefit: This approach simplifies your backend code significantly. Your server only needs to know the user’s permanent ID and doesn’t need to receive or manage temporary anonymous IDs.

Method 2: Use server-side identification

This method is an alternative if you cannot or prefer not to make the identify call from your frontend. In this flow, you must capture the anonymousId from the browser and send it to your backend to be used in your first Segment identify call.

Step A: Get the anonymousId on the frontend

Use this helper function on your website to retrieve the Usermaven anonymous ID from the browser cookie.

/**
 * Retrieves the Usermaven anonymous ID from the browser cookie.
 * @returns {string|null} The anonymous ID or null if not found.
 */
function getUsermavenAnonymousId() {
  const cookie = document.cookie.split('; ').find((c) => c.startsWith('__eventn_id_='));
  return cookie ? cookie.split('=')[1] : null;
}
 
// When a user signs up, get the ID and send it to your server
const anonId = getUsermavenAnonymousId();
// fetch('/api/signup', { body: JSON.stringify({..., anonymousId: anonId }) });

Step B: Use the anonymousId on the backend

On your server, retrieve the anonymousId you passed from the frontend and place it in the context.anonymousId field of your Segment identify call.

<?php
// This example assumes you have the Segment PHP SDK installed.
use Segment\Segment;
 
Segment::init("YOUR_SEGMENT_WRITE_KEY");
 
// 1. Get the anonymousId passed from your frontend request.
$anonymousId = $_POST['anonymousId'];
 
// 2. Get the user's real ID after they sign up or log in.
$userId = 'user_12345';
 
// 3. Make the Segment identify call with anonymousId in the context.
Segment::identify([
  "userId" => $userId,
  "traits" => [ "email" => "test@example.com" ],
  "context" => [ "anonymousId" => $anonymousId ]
]);
 
Segment::flush();
?>

A note on server-side events: Passing the user’s IP address

Regardless of which identification method you choose, it’s a best practice to pass the client’s real IP address for any server-side events you send to Segment. By default, Segment’s server-side libraries will send your server’s IP address, leading to incorrect geolocation data.

Capture the client’s IP from the web request and include it in the context.ip field.

Example: Passing the IP in Laravel (PHP)

<?php
use Segment\Segment;
 
Segment::init("YOUR_SEGMENT_WRITE_KEY");
 
// Get the client's IP address from the request.
$clientIp = request()->ip();
 
Segment::track([
  "userId" => "user_12345",
  "event" => "Subscription Upgraded",
  "context" => [
    "ip" => $clientIp // This ensures correct geolocation.
  ]
]);
 
Segment::flush();
?>

Testing and verification

After setting up your integration, follow these steps to verify that data is flowing correctly.

1. Verifying the basic connection

First, check that events are successfully passing from Segment to Usermaven in real-time.

  • In Segment: Navigate to your Source and open the Debugger tab. Trigger an event in your application and watch for it to appear in the live event stream. Check that it was successfully delivered to the Usermaven destination.
  • In Usermaven: Navigate to Configure > Events Activity. You should see the same event from Segment appear here within a few moments.

2. Verifying identity stitching (for the hybrid approach)

This is the definitive test to ensure anonymous and known user activity are being connected properly.

  1. Open your website in a new incognito browser window. This ensures you have a fresh anonymous session.
  2. Browse a few pages on your site. This will generate anonymous Page Viewed events via the Usermaven pixel.
  3. Perform the action that identifies the user (e.g., create a new account or log in). This should trigger your usermaven.identify() call or your server-side Segment identify call with the anonymousId.
  4. Perform an action that triggers a server-side event through Segment (e.g., “Completed Onboarding Step”).
  5. Check the user’s profile in Usermaven:
    • Go to the Contacts Hub and find the user you just created via their email or user ID.
    • Open their profile and view their activity timeline.
    • You should see a single, unified timeline containing all events in the correct order: the anonymous page views, the identification event, and the subsequent server-side event.

If the timeline is complete and unified, your identity stitching is working perfectly.

What to do if events are not appearing

  • Check for 401 Unauthorized errors in the Segment Debugger. This means your API key is incorrect. Verify the key in your Usermaven destination settings in Segment.
  • Check for 400 Bad Request errors. This usually means the data sent was incomplete or malformed. Ensure your events have the required fields.
  • If events are not stitched correctly, ensure the userId you send from your backend Segment calls exactly matches the userId used in your frontend usermaven.identify() call.

Additional resources

Last updated on
Installing Usermaven