# External BI tools
Source: https://docs.segmentstream.com/attribution/bi-tools

Connect SegmentStream pre-aggregated data in Google BigQuery to external BI tools like Looker Studio.

<Note>
  External BI tools are available only on the [enterprise plan](https://segmentstream.com/pricing).
</Note>

In addition to fully customisable built-in reports, you can use pre-aggregated data stored in your Google BigQuery to build custom reports using third-party BI tools like Looker Studio.

## Looker Studio integration guide

<Steps>
  <Step title="Clone the template">
    Copy the report from [the Looker Studio template](https://lookerstudio.google.com/reporting/72ea5165-865f-46ac-91c4-631ebab8c1aa/page/rUtYD).
  </Step>

  <Step title="Access data sources">
    Navigate to the data sources section: **Resource > Manage added data sources**.

    <img alt="Data sources section" />
  </Step>

  <Step title="Edit data source">
    Click the **Edit** button.

    <img alt="Edit data source" />
  </Step>

  <Step title="Modify connection">
    Select **Edit Connection** at the top left corner.

    <img alt="Edit connection" />
  </Step>

  <Step title="Update project and dataset">
    Replace the existing project and dataset with the appropriate dataset from your project settings.

    <img alt="Project and dataset configuration" />

    ```sql theme={null}
    SELECT *
    FROM `YOUR_PROJECT.YOUR_DATASET.bi_report_v4`(
      PARSE_DATE('%Y%m%d', @DS_START_DATE),
      PARSE_DATE('%Y%m%d', @DS_END_DATE),
      30
    );
    ```
  </Step>

  <Step title="Reconnect">
    Click the **Reconnect** button to apply the changes.
  </Step>
</Steps>

After following these steps, you will have Looker Studio connected to your SegmentStream data. This integration lets you visualise and analyse data in more versatile ways using all the features Looker Studio offers.


# Custom dimensions
Source: https://docs.segmentstream.com/attribution/custom-dimensions

Create custom dimension groupings based on standard dimensions for tailored attribution reports and optimisation portfolios.

You can group sessions and ad platform data by custom dimensions based on standard dimensions such as Source, Medium, Ad Platform, and more.

Custom dimensions let you create reports tailored to your business logic. For instance, you can create a custom dimension to distinguish between paid and non-paid traffic by combining all CPC mediums under a "paid" group and all organic mediums under a "non-paid" group. You can then use this custom dimension in reports to see total metrics for each group.

Custom dimensions can also be used in optimisation portfolios to receive budget allocation recommendations for each custom group.

## Channel custom dimension

The **Channel** custom dimension is predefined and automatically available in all projects. It streamlines analysis of traffic from different sources.

### Default channel groups

* **Google Ads** -- all sessions and ad spend from paid Google Ads.
* **Facebook** -- all sessions and ad spend from paid Facebook.
* **Organic Search** -- all sessions from organic search traffic.
* **Organic Social** -- all sessions from organic social network traffic.
* **Email** -- all sessions from email and newsletter traffic.
* **Referral** -- all other referral traffic.
* **Direct** -- all sessions from direct website access (typing the URL, bookmarks, or untracked sources).

Edit the Channel custom dimension to reflect your reporting requirements. For instance, add new groups for additional ad platforms your business uses.

## How to set up a custom dimension

<Steps>
  <Step title="Navigate to the reports section">
    Open the Attribution reports.
  </Step>

  <Step title="Open the dimensions panel">
    Click **Dimensions**.
  </Step>

  <Step title="Add a custom dimension">
    Scroll down the dimensions list and click **+ Add custom dimension**.
  </Step>

  <Step title="Name your dimension">
    Enter a name for your custom dimension.
  </Step>

  <Step title="Create custom groups">
    Name your first custom group and set the filters that apply to it. For more information on filtering, see [data filtering](/attribution/data-filtering).
  </Step>

  <Step title="Add more groups">
    Click **+ Add group** to create additional custom groups.
  </Step>

  <Step title="Save">
    Click **Save**. Your custom dimension is now available in reports and optimisation portfolios.
  </Step>
</Steps>

<Warning>
  The order of custom groups matters. Filtered data trickles from the top group to the ones below. For example, if you want a "Branded" group for branded CPC campaigns and a "CPC" group for all CPC campaigns, place "CPC" below "Branded". Otherwise, all branded campaigns will be reported within the "CPC" group.
</Warning>

<img alt="Custom dimensions setup" />

## Using custom dimensions in reports

To view data grouped by your custom dimension, select it from the dimension list like any other dimension. Custom dimensions can be edited at any time by clicking the cogwheel icon.

<img alt="Custom dimensions in reports" />

Any data that does not belong to any custom group within the dimension is displayed in the "Other" row in reports.

<img alt="Other row in reports" />

## Using custom dimensions in optimisation portfolios

Custom dimensions are visible as granularity options during portfolio creation only if they are built from one of these dimensions:

* Ad Platform
* Ad Account
* Campaign
* Campaign Type
* Medium
* Source
* Source/Medium

They will not appear as options if other dimensions are used.

Learn how to use custom dimensions in your optimisation portfolio in the [portfolio setup](/optimization/portfolio-setup) guide.


# Customisation
Source: https://docs.segmentstream.com/attribution/customisation

Customise attribution report tables by modifying dimensions, metrics, conversions, sorting, and visualisation options.

Customise your tables in SegmentStream using the **Dimensions**, **Metrics**, and **Conversions** controls.

## Dimensions

Dimensions represent specific categories or slices of data you want to analyse, often in the form of strings such as campaign names, countries, or keywords.

You can find the description of all available dimensions on the [dimensions](/attribution/dimensions) page.

### How to modify

<Steps>
  <Step title="Open the dimensions panel">
    Click the **Dimensions** button above the table.
  </Step>

  <Step title="Select and arrange dimensions">
    In the window that appears, select the dimensions you want on the left and arrange their order on the right.
  </Step>
</Steps>

<Note>
  Order matters. SegmentStream uses a drill-down logic, letting you explore more detailed views with a single click.
</Note>

<img alt="Dimensions configuration" />

## Metrics

Metrics are numerical values corresponding to dimension values.

### How to modify

<Steps>
  <Step title="Open the metrics panel">
    Click the **Metrics** button above the table.
  </Step>

  <Step title="Select metrics">
    In the window that appears:

    * The **Metrics** section contains general metrics (for example, Clicks, Sessions, Users).
    * The **Conversion metrics** section contains performance-related metrics such as conversion rate or ROAS.
  </Step>
</Steps>

<img alt="Metrics configuration" />

## Conversions

SegmentStream lets you add and compare multiple conversions and attribution models side by side.

### How to modify

<Steps>
  <Step title="Open the conversions panel">
    Click the **Conversions** button.
  </Step>

  <Step title="Select conversions and models">
    In the window that appears, select the desired conversions and attribution models.
  </Step>

  <Step title="Rearrange the order">
    Use drag-and-drop with the handler to the left of each conversion name.
  </Step>
</Steps>

<img alt="Conversions configuration" />

## Sorting and visualisation

### Sorting

Click a metric name to sort data. Click again to reverse the order.

<Note>
  SegmentStream does not currently support ordering by dimension values.
</Note>

### Visualisation options

Under the name of each metric you will find icons for three visualisation types:

* **Show on chart** -- display a metric on the chart.
* **Percentage of total** -- show values as a percentage of the total.
* **Percentage difference from average** -- available for metrics like Conv. Rate, Cost / Conv., CRR, and ROAS.

### Selecting and analysing dimension values

To visualise specific dimensions on your chart:

1. In the dimensions column, find the checkbox next to each dimension value.
2. Select one or more checkboxes. For instance, check both "Campaign 1" and "Campaign 2" for a comparative analysis.
3. Uncheck the **Total** option to focus only on specific dimensions.
4. The chart updates to display data for the checked dimensions.
5. To reset selections, click the top checkbox which toggles select all/deselect all.

## Saving your customisations

1. Click the **Save** button in the top right to save changes.
2. To save your current view as a new one, click the dropdown next to **Save** and choose **Save as new**. Provide a name for your new view in the window that appears.


# Data filtering
Source: https://docs.segmentstream.com/attribution/data-filtering

Filter attribution report data by date ranges and dimension values to focus on the metrics that matter.

SegmentStream lets you filter data in two ways: by date and by dimension values.

<Note>
  SegmentStream does not currently support filtering based on metric values.
</Note>

## Filtering by date

To filter data in charts and tables by date:

<Steps>
  <Step title="Open the calendar widget">
    Click the calendar widget at the top left corner.
  </Step>

  <Step title="Select a date range">
    Choose from the predefined ranges:

    * Yesterday
    * Last 7 days
    * Last 14 days
    * Last 28 days
    * Last 30 days
    * Last 90 days
    * Last 12 months
    * Custom

    The **Custom** option lets you define any specific time period using the calendar control.
  </Step>
</Steps>

<img alt="Date filter widget" />

### Comparing time periods

To compare metrics from different periods:

<Steps>
  <Step title="Enable comparison mode">
    Click the **compare** option in the date filter dropdown.
  </Step>

  <Step title="Choose a comparison range">
    Select from the available options:

    * **Preceding period** -- automatically selects a period equal in length to the one you defined.
    * **Preceding period (match day of week)** -- matches in length and starts on the same day of the week.
    * **Same period last year** -- a year-over-year comparison.
    * **Same period last year (match day of week)** -- year-over-year comparison aligned by day of the week.
    * **Custom** -- define your own preceding period using the input fields at the top of the date filter dropdown.
  </Step>
</Steps>

When comparison mode is enabled, each metric table cell displays:

* The value for the current period at the top.
* The value from the compared period at the bottom.
* The calculated difference between the two values.

<Note>
  Charts do not support comparison mode. Charts display data only for the selected current period.
</Note>

## Filtering by dimension values

To filter data in charts and tables based on dimension values:

<Steps>
  <Step title="Open the filters panel">
    Below the chart, click the **Filters not set** button. This displays a window for configuring advanced filters.
  </Step>

  <Step title="Define filter rules">
    Each filter row represents a rule. For example, to view data only for visitors from the UK:

    * Select dimension: `Country`
    * Choose operator: `is equal to`
    * Pick the value for the UK from the dropdown list.
  </Step>

  <Step title="Apply the filter">
    Click the **Apply** button.
  </Step>
</Steps>

You can create multiple rules and connect them using **AND** or **OR** logic.

Examples:

* Display results where `Ad platform is equal to Facebook Ads` AND `Country is equal to United Kingdom`
* Display data where `Country is equal to United Kingdom` OR `Country is equal to US`
* View campaigns with "ES" in their name using `Campaign contains ES`

<img alt="Dimension value filter" />


# Dimensions
Source: https://docs.segmentstream.com/attribution/dimensions

All standard dimensions available in SegmentStream attribution reports, including how each dimension is populated.

This page describes all standard dimensions available in SegmentStream. Read the [custom dimensions](/attribution/custom-dimensions) page to learn how to create custom dimensions based on these.

| Dimension      | Description                                                                               | How it is populated                                                                                                                                      |
| -------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account Name   | The account that led a user to your website.                                              | The name of the account from the ad platform.                                                                                                            |
| Ad Group       | The ad group that led a user to your website.                                             | The name of the ad group from the ad platform.                                                                                                           |
| Ad Name        | The ad that led a user to your website.                                                   | The name of the ad from the ad platform.                                                                                                                 |
| Ad Platform    | The ad platform that led a user to your website.                                          | The name of the ad platform.                                                                                                                             |
| Campaign       | The campaign that led a user to your website.                                             | The name of the campaign from the ad platform.                                                                                                           |
| Campaign Type  | The campaign type that led a user to your website.                                        | The type of the campaign from the ad platform.                                                                                                           |
| City           | The city where the session occurred.                                                      | The name of the city.                                                                                                                                    |
| Client ID      | The unique identifier assigned by Google Analytics to a web browser on a specific device. | The value of the `_ga` first-party cookie. Clicking on it opens a [user-journey exploration](/attribution/user-journey) window.                          |
| Country        | The country where the session occurred.                                                   | The name of the country.                                                                                                                                 |
| Data Source ID | The identifier of the data source that imported the session and ad platform data.         | Event tracking data sources have numeric IDs such as `12345`. If ad platform data is not matched to sessions, it is reported under the `costData` value. |
| Date           | The date of the reported data.                                                            | Date in `YYYY-MM-DD` format.                                                                                                                             |
| Device         | The type of device where the session occurred.                                            | Device type: mobile or desktop.                                                                                                                          |
| Device Brand   | The brand of the device where the session occurred.                                       | Device brand, such as Microsoft or Apple.                                                                                                                |
| Domain         | The domain to which the row is attributed.                                                | The domain to which the session was attributed. If the data is not linked to a session, the domain the ad platform directs to is displayed.              |
| Landing Page   | The URL the user first arrives at during their session.                                   | The full URL of the landing page including parameters.                                                                                                   |
| Medium         | The medium that led a user to your website.                                               | See [Source and Medium values](#source-and-medium-dimension-values) below.                                                                               |
| Region         | The region where the session occurred.                                                    | The name of the region.                                                                                                                                  |
| Source         | The source that led a user to your website.                                               | See [Source and Medium values](#source-and-medium-dimension-values) below.                                                                               |
| Source/Medium  | The source and medium that led a user to your website.                                    | See [Source and Medium values](#source-and-medium-dimension-values) below.                                                                               |
| Targeting Name | The keyword that led a user to your website.                                              | The full keyword.                                                                                                                                        |
| User ID        | The unique user identifier assigned to a logged-in user.                                  | The user identifier as recognised by the website. Clicking on it opens a [user-journey exploration](/attribution/user-journey) window.                   |
| UTM Campaign   | The value of the `utm_campaign` GET parameter of the link that initiated the session.     | Contents of the `utm_campaign` GET parameter of the landing page URL.                                                                                    |
| UTM Content    | The value of the `utm_content` GET parameter of the link that initiated the session.      | Contents of the `utm_content` GET parameter of the landing page URL.                                                                                     |
| UTM Term       | The value of the `utm_term` GET parameter of the link that initiated the session.         | Contents of the `utm_term` GET parameter of the landing page URL.                                                                                        |

## Source and Medium dimension values

The Source and Medium dimensions indicate where website visitors come from. Here is how they are determined:

* **URL parameters** -- when someone lands on your site, SegmentStream first looks for `utm_source` and `utm_medium` parameters in the URL. If these exist, their values are used for Source and Medium. If they are absent, SegmentStream uses the advertising platform name (such as Google Ads or Facebook Ads) as the Source and `cpc` as the Medium.
* **Google traffic** -- if the link contains parameters like `gclid`, `wbraid`, or `gbraid`, indicating traffic from Google, the Source is set to `google` and the Medium to `cpc`.
* **Organic search** -- when visitors come from a search engine's unpaid results, the search engine domain is recorded as Source (for example, `google.com`) and the Medium is set to `organic`.
* **Referral traffic** -- if visitors come from another website, that domain is used as Source and the Medium is set to `referral`.
* **Direct visits** -- if visitors type your URL directly into their browser, or the source cannot be identified, Source is set to `(direct)` and Medium to `(none)`.


# Export table data
Source: https://docs.segmentstream.com/attribution/export

Export attribution report data to CSV or Google Sheets for further analysis.

SegmentStream lets you export data from your configured report for further analysis in spreadsheets or integration into other applications.

## Steps to export your report

<Steps>
  <Step title="Navigate to the report">
    Open the report you want to export.
  </Step>

  <Step title="Click the export button">
    Locate the **Export** button at the right corner above the report table.
  </Step>

  <Step title="Choose the export format">
    Select from the dropdown: **CSV** or **Google Sheets**.
  </Step>
</Steps>

## Data flattening

SegmentStream automatically flattens multi-level reports for streamlined analysis.

For instance, if your report contains multiple dimension levels such as:

* Country
  * Source / Medium
    * Campaign

The exported data is presented in a flat table format:

| Country | Source / Medium | Campaign    | Metric 1 | Metric ... |
| ------- | --------------- | ----------- | -------- | ---------- |
| UK      | Google / CPC    | Summer Sale | 1000     | 53         |
| UK      | Google / CPC    | Remarketing | 100      | 4          |

## Export limitations

Be aware of row limits when exporting to ensure data completeness:

### CSV export

* **Maximum rows:** 1,000,000
* If your report exceeds this limit, refine the date range, filter out less critical data, or segment your export into multiple CSV files.

### Google Sheets export

* **Maximum rows:** 50,000
* Google Sheets has its own row limits. If your report exceeds this, break it into smaller parts or use CSV export for larger datasets.


# Attribution FAQ
Source: https://docs.segmentstream.com/attribution/faq

Frequently asked questions about SegmentStream attribution reports, data discrepancies, dimension values, and platform-specific behaviour.

<AccordionGroup>
  <Accordion title="Why aren't the number of users and sessions the same in GA4 and SegmentStream reports?">
    The discrepancies between GA4 and SegmentStream user and session counts can arise due to several reasons:

    1. **GA4 modelling** -- by default, GA4 uses machine learning to estimate metrics for users and sessions who have not given consent for analytics cookies. SegmentStream shows user and session metrics based on users who have given consent, and uses machine learning only for conversion-related metrics. To see the real number of tracked users and sessions in your GA4 reports, switch your "Reporting identity" to the "Observed" setting. For more details, see the [GA4 modelling documentation](https://support.google.com/analytics/answer/11161109).

    2. **Filters in GA4** -- your GA4 property might have filters applied, such as those filtering out internal traffic. See the [GA4 filters documentation](https://support.google.com/analytics/answer/13296761) for details.

    3. **Session definitions** -- GA4 and SegmentStream use different logic to define a session. In GA4, once a session starts, it continues until there is a 30-minute gap between events. SegmentStream can start a new session with a click to a paid channel with UTM parameters.

    4. **Timezone discrepancies** -- your GA4 property and SegmentStream project might use different time zones.

    To get a more consistent view, focus on the "users" metric. If you notice a difference greater than 1%, contact support via the admin panel.
  </Accordion>

  <Accordion title="Why do some landing page dimension values reported under paid source/medium not contain UTM tags?">
    This occurs because of how the source/medium is attributed to sessions. The source/medium is determined using the **last non-direct click attribution model**, which tracks the last source that brought the user to your site before a direct session.

    However, the landing page URL is captured from the session that appears within the selected date range. These two values can come from different sessions. You can explore all the sessions of a particular user by adding the User ID or Client ID dimension to your report and opening the [user-journey exploration](/attribution/user-journey).
  </Accordion>

  <Accordion title="Why is &#x22;(not attributed)&#x22; reported as a dimension value?">
    The "(not attributed)" label appears in ad platform dimensions (for example, account name, campaign name, campaign type) when traffic is recognised as coming from an ad platform but cannot be linked to a specific campaign, leaving the values unknown.

    It also appears when user or session data cannot be displayed due to privacy restrictions, or when custom conversions are reported without any associated tracked sessions. These conversions still contribute to the machine learning-based attribution model.
  </Accordion>

  <Accordion title="Why is &#x22;(not set)&#x22; reported as a dimension value?">
    The "(not set)" label appears in ad platform dimensions (for example, ad group name, campaign type) when traffic is associated with an ad platform and campaign but the selected dimension is not available or supported by the platform. For example, Google Ads search campaigns do not support the "Ad" dimension but do support "Targeting Name (keyword)", while Performance Max campaigns support neither.

    The label also appears in behavioural data dimensions when data cannot be displayed due to privacy restrictions or when the selected dimension is not available. For example, sessions from a URL without a `utm_campaign` parameter are reported as "(not set)" under the UTM Campaign dimension.
  </Accordion>

  <Accordion title="Why aren't some sessions with paid source/medium dimensions reported under their respective ad platform?">
    SegmentStream's algorithm aims to identify traffic from each ad platform, even if it cannot be attributed at the campaign level. However, several factors can prevent proper attribution:

    1. **Broken URLs** -- if campaign URLs contain typos or the website modifies or removes UTM parameters, tracking information might not be recorded.
    2. **Uncommon URL shorteners** -- some URL shorteners prevent UTM tag extraction, disrupting campaign tracking. If you use an uncommon URL shortener, notify the support team.
    3. **Auto-tagging without UTMs or utm\_id** -- sessions may not be tracked if only `gbraid` or `wbraid` parameters are used without UTM tags. Follow the UTM tagging best practices to avoid this.
    4. **Clicks from unconnected ad accounts** -- if you have multiple ad accounts and have not connected all of them in the SegmentStream data source, traffic from unconnected accounts will not be attributed to campaigns.
    5. **Old UTMs, bookmarks, or link sharing** -- traffic from old UTM links, bookmarks, or shared links can affect data accuracy. Sessions can only be stitched to campaigns within 30 days of the last click.
    6. **Unsupported tagging** -- incorrect use of tags, such as in product feed links, may prevent session tracking.
  </Accordion>

  <Accordion title="How does iOS 17 impact marketing analytics?">
    iOS 17 removes the `click_id` parameter (`gclid`, `fbclid`, etc.) from URLs. For example, a URL like:

    ```
    https://site.com/?utm_source=google&utm_medium=cpc&utm_campaign=1467008&gclid=nvwieu5tryt5q9rut9wruqt33
    ```

    becomes:

    ```
    https://site.com/?utm_source=google&utm_medium=cpc&utm_campaign=1467008
    ```

    **What this means for analytics:**
    The `gclid` (Google Click ID) is a parameter that lets Google associate specific conversions with ad clicks. Without it, there is no direct connection between a user action and an ad click. Data will be presented at a more aggregated level, potentially limiting insight depth.

    **Solution:**
    Implement `utm_id` in your tracking URLs to maintain maximum reporting granularity. Refer to the [Facebook data source guide](/project-configuration/data-sources/facebook) for implementation details.
  </Accordion>

  <Accordion title="Why do I see sessions with non-Google source/medium dimensions under the Google Ads ad platform?">
    SegmentStream auto-associates sessions with Google Ads when they include click parameters like `gclid`, `wbraid`, or `gbraid`.

    This can occur when:

    1. Other advertising platforms purchase Google Ads traffic, for example, affiliate marketing networks like AWIN.
    2. There is a human error leading to inclusion of Google-specific click ID parameters in ad links of other platforms.
  </Accordion>

  <Accordion title="Do your reports show assisted conversions or view-through conversions from each platform?">
    SegmentStream reports do not display assisted or view-through conversions from individual platforms. Instead, SegmentStream offers a unique attribution model that highlights the incremental impact of each marketing channel. This model considers user behaviour on your website and brings together data about user engagement with your brand on platforms like Facebook, YouTube, and others.
  </Accordion>

  <Accordion title="Why are there more clicks than tracked users in paid Facebook Ads reported within SegmentStream?">
    The main reason is that users may not accept cookies when they engage with Facebook ads. Review your consent mode popup design to make it easier for users to accept cookies.

    Another reason is that users might click on ads multiple times. This is common with catalogue-type ads, where users click on several products. Facebook reports each click as an [outbound click](https://www.facebook.com/business/help/186560398499760), but SegmentStream counts them as one user. Compare the [unique outbound click](https://www.facebook.com/business/help/272487833189895) metric in Facebook with the number of users reported by SegmentStream.
  </Accordion>

  <Accordion title="Why are there more clicks than tracked users in paid TikTok ads reported within SegmentStream?">
    SegmentStream uses TikTok's "Clicks (Destination)" metric to report clicks. This metric includes not only clicks that lead users to websites, apps, or app stores, but also interactions such as clicking on the profile picture, caption, profile name, CTA button, and sliding to the left. Many of these interactions do not result in website visits, causing a higher number of reported clicks compared to tracked users.
  </Accordion>
</AccordionGroup>


# Metric approximation
Source: https://docs.segmentstream.com/attribution/metric-approximation

How SegmentStream approximates publisher platform metrics when broken down by dimensions not available from the publisher.

SegmentStream reports combine data from tracked user actions with data exported from connected publisher platforms.

When analysing data, metrics such as impressions, clicks, costs, and their derivatives (for example, cost per click, cost per conversion) exported from publisher platforms may not be accurately reported when broken down by dimensions that are not available from the publisher.

## Solution

To address data granularity limitations from publisher platforms, SegmentStream displays approximated values for these metrics. Approximation is based on the proportion of sessions within the selected report dimension.

## Affected dimensions

This behaviour primarily affects geo- and device-specific dimensions, as indicated by tooltips in the report dimension selection menu.

## Logic

For approximation to apply, SegmentStream must be able to match the tagging used across all levels within a specific campaign to sessions.

If the tagging is not matched down to the lowest level of the advertising hierarchy within a specific campaign, approximation is not applied at any dimension level.

Metrics from publisher data that are not linked to any sessions are labelled as `(not tracked)` in reports broken down by dimensions not available from the publisher.

<img alt="Metric approximation in reports" />


# Attribution
Source: https://docs.segmentstream.com/attribution/overview

Assess digital marketing campaign outcomes with adaptable attribution reports covering key metrics from Cost per Conversion to ROAS.

The Attribution section provides tools for assessing your digital marketing campaign outcomes. Attribution reports are adaptable and let you quickly gauge key metrics, from Cost per Conversion to ROAS. You can compare multiple attribution models side by side within a single view.

## Getting started

Before using attribution reports:

* Ensure [events tracking](/project-configuration/events-tracking) is set up.
* Connect at least one [data source](/project-configuration/data-sources/overview).
* Define a minimum of one [conversion event](/project-configuration/conversions).

## Navigation

* To access reports, navigate to the **Attribution** tab in the main menu.
* To switch between reports, click the report name.

## Charts

You can visualise data through line charts.

* **Multiple metrics** -- each line in the chart corresponds to a specific metric you have added to your table.
* **Grouping options** -- data can be grouped by day, week, or month.

## Table

Tables present data in three column types:

* **Dimensions** -- for example, Source/Medium, Campaign.
* **General metrics** -- for example, Cost, Impressions, Clicks, Users.
* **Conversion metrics** -- for example, Conversions, Conversion Value, ROAS.

Modify the table columns to your preference using the control buttons above. Learn more about [customisation](/attribution/customisation).

<Tip>
  To export data from the table to CSV or Google Sheets, click the export button at the top right of the table.
</Tip>

## Filters

* **Date filters** -- located above the chart, this lets you specify a date range or compare two distinct periods such as the previous week.
* **Data filters** -- beneath the chart, refine your results based on specific criteria. For instance, filter results where `Ad platform equals Facebook Ads` AND `Country is the UK`.

Learn more about [data filtering](/attribution/data-filtering).

## Managing reports

Attribution reports are fully customisable. Tailor your view by adjusting the date range, setting filters, and adding or removing dimensions and metrics.

To save your customised report, select **Save** or **Save as new** in the top right corner. This generates a new report view you can retrieve by selecting the report name from the dropdown menu in the top left corner.

## In this section

<CardGroup>
  <Card title="Dimensions" icon="table-columns" href="/attribution/dimensions">
    Standard and custom dimensions available in attribution reports.
  </Card>

  <Card title="Data filtering" icon="filter" href="/attribution/data-filtering">
    Filter report data by date ranges and dimension values.
  </Card>

  <Card title="Customisation" icon="sliders" href="/attribution/customisation">
    Customise table dimensions, metrics, conversions, sorting, and visualisation.
  </Card>

  <Card title="Custom dimensions" icon="layer-group" href="/attribution/custom-dimensions">
    Create custom groupings based on standard dimensions for tailored reports.
  </Card>

  <Card title="Metric approximation" icon="chart-area" href="/attribution/metric-approximation">
    How SegmentStream approximates metrics when publisher data lacks granularity.
  </Card>

  <Card title="Export table data" icon="file-export" href="/attribution/export">
    Export report data to CSV or Google Sheets.
  </Card>

  <Card title="External BI tools" icon="chart-pie" href="/attribution/bi-tools">
    Connect SegmentStream data to Looker Studio and other BI tools.
  </Card>

  <Card title="User-journey exploration" icon="route" href="/attribution/user-journey">
    Analyse how users navigate your website and how attribution models assign credit.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/attribution/faq">
    Frequently asked questions about attribution reports.
  </Card>
</CardGroup>


# User-journey exploration
Source: https://docs.segmentstream.com/attribution/user-journey

Analyse how users navigate your website and how different attribution models assign conversion credit.

User-journey exploration lets you analyse how users navigate through your website, app, or digital platform. It also helps you understand how different sources receive credit under various attribution methods, including the **Visit Scoring** attribution model.

## How to open a user-journey exploration

<Steps>
  <Step title="Open the Attribution module">
    Navigate to the **Attribution** module.
  </Step>

  <Step title="Add a Client ID or User ID dimension">
    Add one of these dimensions to the report:

    * **Client ID** -- shows user journeys on one specific device.
    * **User ID** -- shows a cross-device user journey, consolidating sessions from all associated Client IDs. Requires `user_id` to be collected in your GA4.
  </Step>
</Steps>

<img alt="Adding Client ID or User ID dimensions" />

## User journey overview

A user-journey exploration displays:

* **Location and device type/brand**
* **Session list** with the following columns:
  * **Visit** -- initial timestamp and client ID.
  * **Source** -- the Source/Medium and Campaign that initiated the session.
  * **Activity** -- the number of events tracked, session duration, number of conversions, and whether the user may have entered an audience.

Clicking on a session reveals a detailed timeline of all events (with timestamps and URLs) that took place during that session.

## Analysing attribution using user-journey explorations

By adding conversions tracked under both **Visit Scoring** and **Last Click** attribution models, then including a breakdown by Client ID or User ID, you can compare how each model credits conversions for individual users. This shows how Visit Scoring differs from the standard last-click method.

Below are two examples demonstrating how to use user-journey explorations to understand attribution outcomes.

### Example 1

**Scenario:** No last-click conversions were recorded for this Client ID, but the Visit Scoring model attributed a score.

<Steps>
  <Step title="Check the report">
    The table shows the Last Click model has 0 conversions, while Visit Scoring attributed a score.

    <img alt="Report showing Visit Scoring vs Last Click" />
  </Step>

  <Step title="Open the user-journey exploration">
    The user first arrived via a Generic Campaign, then later via a Brand Campaign, indicating research and interest.

    <img alt="Session list for Example 1" />
  </Step>

  <Step title="Inspect the session details">
    Expanding each session reveals numerous `non_idle` events, illustrating significant active time on the site.

    <img alt="Session event details" />
  </Step>

  <Step title="Attribution logic">
    Because the [attribution model](/project-configuration/attribution-models) is configured to consider brand-campaign traffic as less significant, the scoring from those sessions is credited to the Generic Campaign.

    <img alt="Attribution credit assignment" />
  </Step>
</Steps>

### Example 2

**Scenario:** The Client ID has a Last Click conversion, but the Visit Scoring model awarded no score.

<Steps>
  <Step title="Check the report">
    The report shows Last Click attributed a conversion, but Visit Scoring scored it at 0.

    <img alt="Report showing Last Click vs Visit Scoring" />
  </Step>

  <Step title="Open the user-journey exploration">
    The user had only one session lasting a single second, during which they converted immediately.

    <img alt="Single short session" />
  </Step>

  <Step title="Attribution logic">
    Because the session was so short, the Visit Scoring model treats it as a "fragmented" visit. It infers the purchase decision was influenced by a prior source, so it does not award any score to the campaign associated with this final click.
  </Step>
</Steps>

## Key takeaways

* **Deeper understanding of Visit Scoring** -- comparing Last Click and Visit Scoring helps you see how longer or multiple sessions contribute to final conversion credit.
* **Actionable insights** -- user-journey exploration lets you optimise campaigns by identifying which touchpoints truly drive conversions, which are brand navigations, and which might be too short or fragmented for meaningful attribution credit.


# Dashboards
Source: https://docs.segmentstream.com/dashboards

Create customizable visual dashboards to monitor and analyze your project's performance metrics at a glance.

Dashboards are customizable visual representations of your project's performance metrics. They provide an intuitive overview of your data, enabling you to monitor and analyze key insights at a glance. You can create multiple views tailored to your specific needs to track progress, identify trends, and make informed decisions.

<img alt="Dashboard overview with performance metrics" />

## Getting started

Before using the dashboards module:

* Set up [event tracking](/project-configuration/events-tracking).
* Connect at least one [data source](/project-configuration/data-sources/overview).
* Define at least one [conversion](/project-configuration/conversions).

## Navigation

* Access the dashboards module by navigating to the **Dashboards** tab in the main menu.
* Switch between different dashboards by clicking on the dashboard name.

## Date filters

The date filter in the top right lets you specify a date range to view metrics and charts, or compare two distinct periods such as the previous week.

## Creating dashboards

Your project comes with a default "Overview" dashboard displaying basic metrics. You can customize it or create a new one.

<Steps>
  <Step title="Open the dashboard menu">
    Click on the name of the current dashboard in the left part of the top menu.
  </Step>

  <Step title="Add a new dashboard">
    Click **+ Add dashboard**.
  </Step>
</Steps>

## Dashboard customization

<Steps>
  <Step title="Enter edit mode">
    Click the three-dot menu at the top right of your screen and select **Edit**.
  </Step>

  <Step title="Arrange your dashboard">
    While in edit mode, you can:

    * Rearrange blocks by dragging and dropping them.
    * Resize blocks by dragging the lower right corner.
    * Add new widgets by clicking **+ Add widget** in the top menu.
  </Step>

  <Step title="Save changes">
    Click the **Save** button on the top right corner. All adjustments are shared with users who have access to the project.
  </Step>
</Steps>

## Widget settings

When adding or editing a widget, you can preview it before adding it to your dashboard.

### Configuration

In the Configuration tab, select the visualization type and the metric you want to display.

<Tabs>
  <Tab title="Metric">
    Displays the numerical value of a single metric.
  </Tab>

  <Tab title="Line Chart">
    Visualizes data trends over time.
  </Tab>

  <Tab title="List">
    Displays a metric broken down by a dimension.
  </Tab>
</Tabs>

<Tip>
  Read more about all available dimensions in the [Dimensions](/attribution/dimensions) guide.
</Tip>

When selecting a conversion metric, an additional field appears where you must select the conversion and the [attribution model](/project-configuration/attribution-models) used to calculate the metric.

<img alt="Widget configuration panel" />

### Filters

Use the Filters tab to apply filters to metrics based on dimension values.

Each filter row represents a rule. For example, to view data exclusive to visitors from the UK:

1. Select Dimension: **Country**
2. Choose Operator: **is equal to**
3. Pick the value for the United Kingdom from the dropdown.

You can establish multiple rules and connect them using **AND** or **OR** logic.

Examples:

* Display metrics where **Ad platform is equal to Facebook Ads** AND **Country is equal to United Kingdom**
* Display metrics where **Country is equal to United Kingdom** OR **Country is equal to United States**
* Display metrics where **Campaign contains the word SALE**

Widgets with applied filters can be identified by the filter list icon. Hovering over it displays the dimensions used in the applied filters.

<img alt="Widget filter configuration" />


# Geo Tests
Source: https://docs.segmentstream.com/geo-tests

Conduct geo-incrementality experiments to measure the real sales impact of your paid media investments using controlled test and control markets.

SegmentStream's Geo Tests module allows you to conduct experiments that measure the real sales impact of your paid media investments.

By comparing the performance of a control market (where marketing activity remains unchanged) with a test market (where marketing activities are modified), you can directly observe the impact of these changes.

Currently, SegmentStream supports one type of treatment -- **holdout** -- where campaigns in the test market are completely disabled during the experiment. This allows you to evaluate their incrementality by observing the drop in conversions compared to the control market.

## Getting started

Before using the Geo Tests module:

* Set up [event tracking](/project-configuration/events-tracking).
* Connect at least one [data source](/project-configuration/data-sources/overview).
* Define at least one [conversion](/project-configuration/conversions).
* Ensure you have at least two months of conversion data.

## Navigation

You can find the Geo Tests module in the left menu.

## Setting up an experiment

<Steps>
  <Step title="Create the experiment">
    Name the experiment, select the conversion and campaigns that will be used to measure incrementality, and choose an estimated experiment start date. All settings except for the conversion can be changed later.

    <img alt="Experiment settings form" />
  </Step>

  <Step title="Configure market selection">
    SegmentStream automatically selects the test and control markets, but you can adjust them if necessary.

    <img alt="Market selection interface" />
  </Step>

  <Step title="Pause campaigns in test regions">
    Pause the targeted marketing efforts within the designated test regions.
  </Step>

  <Step title="Evaluate results">
    Review the experiment results to gain insights into campaign incrementality.
  </Step>
</Steps>

## Market selection

### Market split

Select the geographic level at which the test and control markets will be chosen. Default options include city, country, and region.

<Note>
  Default options rely on IP geolocation, which provides only approximate user locations. Using fine-grained geo splits such as "city" may significantly impact experiment results due to approximation inaccuracies.
</Note>

To use more reliable geo data, SegmentStream provides the option to utilize CRM data by exporting it into BigQuery and creating a custom conversion that includes the geo data. The parameters from your custom conversions appear in the selector under the **Custom parameters** label.

For assistance in utilizing CRM data, contact your SegmentStream manager.

### Granularity

If there are not enough daily conversions to measure incrementality, select the **Weekly** granularity option. This affects both the sales cycle setting and how data is visualized in the conversion and cost charts.

### Sales cycle

Enter the typical duration for a user to achieve the set goal from their initial interaction with your brand. Understanding the sales cycle is essential as it determines the period over which the impact of a campaign should be evaluated.

### Test and control markets

The system analyzes trends, seasonality, and volume across various regions, choosing those with the highest correlation. A synthetic control approach is used to scale data from control regions to more closely align with the test regions' data.

### Exclude markets

You can exclude any markets that should not be included in the experiment. After selecting the excluded markets, the test and control markets are recalculated.

### Minimum detectable effect

The minimum detectable effect (MDE) is detected once the test and control markets are selected. MDE is the smallest change in results that an experiment can reliably detect. If the incrementality is lower than this number, it cannot confidently be attributed to the campaigns within the experiment.

<Warning>
  When SegmentStream detects that the MDE exceeds a critical value, a warning is displayed indicating that the selected experiment configuration is not recommended.
</Warning>

## Results

Once your experiment is launched, the metrics reflecting its progress are displayed.

### Incrementality

This metric presents the calculated incrementality of the campaigns involved in the experiment, as well as the total conversion difference between the test and control markets.

### Experiment evaluation

Once the experiment is done, a banner informs you if the results are strong enough to make clear conclusions and whether it is suggested to run the experiment again.

<img alt="Experiment results with incrementality metrics" />

## Charts

### Conversion chart

The conversion chart displays two lines representing conversion trends over time for both test and control markets, including the experiment's start and end dates.

Before the experiment starts, the algorithm selects test and control markets so that their lines closely align. Once the experiment begins, the blue line (test markets) is expected to drop below the red line (control markets), indicating the effectiveness of the campaigns included in the experiment.

<img alt="Conversion chart comparing test and control markets" />

### Cost chart

The cost chart shows the trend in advertising expenditure over time for the chosen test markets. It enables you to verify that the treatment is applied correctly throughout the experiment -- indicated by the line remaining close to zero.

<img alt="Cost chart showing ad spend in test markets" />


# Getting started
Source: https://docs.segmentstream.com/mcp/getting-started

Connect your AI tool to SegmentStream MCP in under a minute.

SegmentStream MCP is a self-contained server with built-in measurement skills. Connect your AI tool using the server URL — authentication is handled automatically via OAuth.

## Prerequisites

1. **A SegmentStream account** with access to at least one project
2. **An MCP-compatible AI tool** — Claude.ai, Claude Code, Claude Cowork, Claude Desktop, Codex, Cursor, VS Code, or Windsurf

## Setup by tool

<Tabs>
  <Tab title="Claude.ai (recommended)">
    The fastest way to get started. Once connected in claude.ai, the connection is automatically available in Claude Code, Claude Desktop, and Cowork — no additional setup needed.

    <Steps>
      <Step title="Click Customize">
        Go to [claude.ai](https://claude.ai) and click **Customize** in the left sidebar.

        <Frame>
          <img alt="Claude.ai sidebar with Customize highlighted" />
        </Frame>
      </Step>

      <Step title="Open Connectors">
        Click **Connectors**.

        <Frame>
          <img alt="Customize page showing Skills and Connectors options" />
        </Frame>
      </Step>

      <Step title="Add a custom connector">
        Click the **+** button, then select **Add custom connector**.

        <Frame>
          <img alt="Connectors page with + button and Add custom connector option" />
        </Frame>
      </Step>

      <Step title="Enter the SegmentStream MCP URL">
        Enter a name (e.g. "SegmentStream") and paste the server URL, then click **Add**:

        ```
        https://mcp.segmentstream.com/mcp
        ```

        <Frame>
          <img alt="Add custom connector dialog with SegmentStream name and MCP URL" />
        </Frame>
      </Step>

      <Step title="Connect">
        The connector appears as "Not connected". Click **Connect** to start the OAuth flow.

        <Frame>
          <img alt="SegmentStream MCP connector showing Not connected status with Connect button" />
        </Frame>
      </Step>

      <Step title="Authorize">
        Sign in with your SegmentStream account and click **Allow**.

        <Frame>
          <img alt="SegmentStream authorization page requesting access to projects, reports, and campaign data" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Cowork">
    Cowork uses the same Connectors interface as claude.ai.

    <Steps>
      <Step title="Click Customize">
        Click **Customize** in the left sidebar.

        <Frame>
          <img alt="Claude sidebar with Customize highlighted" />
        </Frame>
      </Step>

      <Step title="Open Connectors">
        Click **Connectors**.

        <Frame>
          <img alt="Customize page showing Skills and Connectors options" />
        </Frame>
      </Step>

      <Step title="Add a custom connector">
        Click the **+** button, then select **Add custom connector**.

        <Frame>
          <img alt="Connectors page with + button and Add custom connector option" />
        </Frame>
      </Step>

      <Step title="Enter the SegmentStream MCP URL">
        Enter a name (e.g. "SegmentStream") and paste the server URL, then click **Add**:

        ```
        https://mcp.segmentstream.com/mcp
        ```

        <Frame>
          <img alt="Add custom connector dialog with SegmentStream name and MCP URL" />
        </Frame>
      </Step>

      <Step title="Connect">
        The connector appears as "Not connected". Click **Connect** to start the OAuth flow.

        <Frame>
          <img alt="SegmentStream MCP connector showing Not connected status with Connect button" />
        </Frame>
      </Step>

      <Step title="Authorize">
        Sign in with your SegmentStream account and click **Allow**.

        <Frame>
          <img alt="SegmentStream authorization page requesting access to projects, reports, and campaign data" />
        </Frame>
      </Step>
    </Steps>

    Once connected, start a new task and ask the agent about your marketing data.
  </Tab>

  <Tab title="Claude Code">
    Run this command in your terminal:

    ```bash theme={null}
    claude mcp add segmentstream \
      --transport http \
      https://mcp.segmentstream.com/mcp
    ```

    On first use, you'll be prompted to authenticate via your browser.

    You can scope the server to your project or your user profile:

    | Flag         | Scope                                 | Config file                 |
    | ------------ | ------------------------------------- | --------------------------- |
    | `-s project` | Shared with your team via `.mcp.json` | `.mcp.json` in project root |
    | `-s user`    | Personal, across all projects         | `~/.claude/settings.json`   |
    | *(default)*  | Local to this project                 | `.mcp.json` in project root |
  </Tab>

  <Tab title="Cursor">
    Open **Settings → MCP** and add a new server, or edit `.cursor/mcp.json` in your project root:

    ```json theme={null}
    {
      "mcpServers": {
        "segmentstream": {
          "type": "http",
          "url": "https://mcp.segmentstream.com/mcp"
        }
      }
    }
    ```

    On first use, you'll be prompted to authenticate via your browser. Restart Cursor to activate the connection.
  </Tab>

  <Tab title="VS Code">
    Create or edit `.vscode/mcp.json` in your project root:

    ```json theme={null}
    {
      "servers": {
        "segmentstream": {
          "type": "http",
          "url": "https://mcp.segmentstream.com/mcp"
        }
      }
    }
    ```

    On first use, you'll be prompted to authenticate via your browser.
  </Tab>

  <Tab title="Windsurf">
    Open **Settings**, search for "MCP", and add:

    ```json theme={null}
    {
      "mcpServers": {
        "segmentstream": {
          "type": "http",
          "url": "https://mcp.segmentstream.com/mcp"
        }
      }
    }
    ```

    On first use, you'll be prompted to authenticate via your browser.
  </Tab>

  <Tab title="Codex">
    <Steps>
      <Step title="Open MCP servers settings">
        In Codex, go to **Settings** → **MCP servers** and click **Add server**.
      </Step>

      <Step title="Select Streamable HTTP">
        Switch the transport selector from **STDIO** to **Streamable HTTP**.
      </Step>

      <Step title="Fill in the form">
        * **Name:** `SegmentStream`
        * **URL:** `https://mcp.segmentstream.com/mcp`

        Leave **Bearer token env var**, **Headers**, and **Headers from environment variables** empty — they aren't needed for the SegmentStream connection.

        Click **Save**.
      </Step>

      <Step title="Authenticate">
        Click **Authenticate** on the saved server. A browser window opens — sign in with your SegmentStream account and click **Allow**. The connection becomes active as soon as the OAuth flow completes.
      </Step>
    </Steps>

    See OpenAI's [Codex MCP docs](https://developers.openai.com/codex/mcp) if you'd rather configure the server via `~/.codex/config.toml` or the `codex mcp` CLI.
  </Tab>

  <Tab title="Other tools">
    Any MCP client that supports the **Streamable HTTP** transport can connect to SegmentStream MCP:

    | Setting        | Value                               |
    | -------------- | ----------------------------------- |
    | Transport      | Streamable HTTP                     |
    | URL            | `https://mcp.segmentstream.com/mcp` |
    | Authentication | OAuth (automatic)                   |

    The server supports both Streamable HTTP and SSE transports.
  </Tab>
</Tabs>

## Verify the connection

After setup, test that the connection works by asking your AI assistant:

```
List my SegmentStream projects
```

The assistant should call the `list_active_projects` tool and return a list of projects you have access to. If you see your projects, the connection is working.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection fails">
    Make sure your AI tool supports MCP and that you've restarted it after adding the server configuration.
  </Accordion>

  <Accordion title="Tools are not showing up">
    Some MCP clients need a restart after adding a new server. Close and reopen your AI tool, then try again.
  </Accordion>

  <Accordion title="OAuth popup doesn't appear">
    Make sure your browser allows popups from the AI tool. Some browsers block popups by default.
  </Accordion>
</AccordionGroup>

## Next steps

Browse the [supported tools](/mcp/supported-tools) to see everything you can do with SegmentStream MCP.


# SegmentStream MCP
Source: https://docs.segmentstream.com/mcp/overview

Connect AI tools to your SegmentStream workspace using the Model Context Protocol (MCP) to query attribution data, manage configurations, and analyze marketing performance.

SegmentStream MCP is a hosted server that gives AI tools secure, read-only access to your SegmentStream workspace through the [Model Context Protocol](https://modelcontextprotocol.io/) — an open standard for connecting AI assistants to external data sources.

Once connected, your AI assistant can query attribution reports, inspect project configurations, explore user journeys, run BigQuery queries against your dataset, and more — all through natural language.

## Why use SegmentStream MCP?

<CardGroup>
  <Card title="Natural language queries" icon="message-lines">
    Ask questions about campaign performance, attribution, and conversions in plain English instead of navigating dashboards.
  </Card>

  <Card title="Secure access" icon="lock">
    Authenticate with OAuth — the server enforces the same permissions as the SegmentStream UI.
  </Card>

  <Card title="Works with any MCP client" icon="plug">
    Compatible with Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, and any tool that supports MCP.
  </Card>
</CardGroup>

## What you can do

With SegmentStream MCP, your AI assistant can:

* **Query attribution reports** — pull campaign performance data by any dimension, date range, and attribution model
* **Analyze conversions** — check conversion statistics, trends, geographic breakdowns, and individual conversion records
* **Explore user journeys** — trace individual user paths and see how attribution credits are distributed
* **Inspect project configuration** — review data sources, attribution models, conversions, audiences, and grouped dimensions
* **Configure measurement** — create projects, connect data sources, define conversions and attribution models, edit channel groupings, and save reports
* **Run BigQuery SQL** — execute queries directly against your project's BigQuery dataset
* **Monitor data quality** — check cost data quality scores, workflow statuses, and incidents
* **Work with audiences** — list audiences, check memberships, and view inclusion statistics
* **Explore portfolio optimization** — review portfolio performance history, optimization scenarios, and budget allocation recommendations

<Note>
  Mutating tools (creating projects, conversions, attribution models, grouped dimensions, saved reports, and connecting data sources) honor the same permissions as the SegmentStream UI. Project members with viewer-only access can call read tools but not write tools.
</Note>

## Example prompts

Here are some things you can ask your AI assistant after connecting SegmentStream MCP:

* "Show me the top 10 campaigns by ROAS for the last 30 days"
* "What is the cost data quality score for our Facebook data source?"
* "List all conversions configured in the project"
* "Show me the user journey for anonymous ID `abc123` over the last 7 days"
* "Run a BigQuery query to count sessions by country for last week"
* "Which attribution models are configured, and which one is the default?"

## Get started

<CardGroup>
  <Card title="Built-in measurement skills" icon="brain" href="/mcp/supported-tools">
    All measurement skills and commands are built into the server — nothing extra to install.
  </Card>

  <Card title="Getting started" icon="rocket" href="/mcp/getting-started">
    Connect any MCP-compatible tool in under a minute with OAuth.
  </Card>

  <Card title="Supported tools" icon="wrench" href="/mcp/supported-tools">
    Browse all available tools grouped by category with example prompts.
  </Card>
</CardGroup>


# Supported tools
Source: https://docs.segmentstream.com/mcp/supported-tools

Complete reference of all SegmentStream MCP tools — grouped by category with parameters, return values, and example prompts.

SegmentStream MCP provides **60+ tools** organized into functional categories. Your AI assistant automatically discovers and uses these tools based on your prompts — you do not need to call them explicitly.

Tools work best when combined. For example, to get a campaign performance report, the assistant will first call `list_active_projects` to find your project, then `list_conversions` and `list_attribution_models` to resolve the right IDs, and finally `run_report` to fetch the data.

<Note>
  Most tools require a `session_id` parameter returned by `analyze_request`. The assistant handles this automatically — you do not need to manage session IDs yourself.
</Note>

## AI agent orchestration

Internal tools that help AI agents plan and validate their work. These are called automatically by the assistant — you do not need to use them directly.

<AccordionGroup>
  <Accordion title="analyze_request">
    Always called at the start of each user turn, before using other SegmentStream tools. Pass the user's message verbatim. Returns project context, relevant configuration, and an analytical approach tailored to the request. If status is `clarify`, the assistant resolves the ambiguity and calls again. If status is `proceed`, the assistant follows the returned approach.

    **Parameters:**

    | Name          | Type   | Required | Description                                                                                |
    | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
    | `user_prompt` | string | Yes      | The user's question or request, verbatim                                                   |
    | `user_intent` | string | No       | What the user wants to achieve. Especially helpful when the message is short ("ok", "yes") |
    | `project_id`  | string | No       | Omit to auto-resolve                                                                       |
    | `session_id`  | string | No       | Session ID from a previous `analyze_request`. Omit on first call                           |

    **Returns:** Project context, configuration details, and a step-by-step analytical approach.
  </Accordion>

  <Accordion title="analyze_response">
    Always called after completing work, before responding to the user. Pass the full draft response. Returns a quality assessment. If status is `approved`, the assistant presents the response incorporating any suggestions. If status is `revise`, the assistant makes corrections and calls again with an updated draft.

    **Parameters:**

    | Name             | Type   | Required | Description                                                                                                      |
    | ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
    | `response_draft` | string | Yes      | The full response planned for the user                                                                           |
    | `feedback`       | string | No       | Product feedback: guidance gaps, tool issues, user friction. Logged for quality improvement, never shown to user |
    | `session_id`     | string | Yes      | Session ID returned by `analyze_request`                                                                         |

    **Returns:** Quality assessment with status (`approved` or `revise`) and suggestions.
  </Accordion>

  <Accordion title="get_report_template">
    Load the report template, design system, and assets for building visual reports. Use format `html` if you can write files to disk, `jsx` if you render artifacts inline.

    **Parameters:**

    | Name         | Type   | Required | Description                                                                    |
    | ------------ | ------ | -------- | ------------------------------------------------------------------------------ |
    | `format`     | string | Yes      | Template format: `html` (for file-based tools) or `jsx` (for inline rendering) |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request`                                       |

    **Returns:** Report template, design system, and assets.

    **Example prompts:**

    * "Build me a visual report for last month's performance"
    * "Create a branded dashboard with the report template"
  </Accordion>
</AccordionGroup>

## Projects and account

Tools for creating, managing, and inspecting projects and user accounts.

<AccordionGroup>
  <Accordion title="list_active_projects">
    List all active SegmentStream projects with their id, name, timezone, type, account, and BigQuery configuration (`bigqueryProjectId`, `bigqueryDatasetId`). Super users also see `serviceAccountEmail`.

    **Parameters:** None

    **Returns:** Array of project objects with ID, name, timezone, type, account info, and BigQuery settings.

    **Example prompts:**

    * "List all my SegmentStream projects"
    * "Which projects do I have access to?"
    * "What is the BigQuery dataset ID for my project?"
  </Accordion>

  <Accordion title="get_project">
    Get project details: name, timezone, currency, type, features, state, `attributionAdjustment`, `maxAttributionWindow`, `workflowState`, and `billingAccount`.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `project_id` | string | Yes      | The project ID                           |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Full project configuration object.

    **Example prompts:**

    * "Show me the details of project X"
    * "What timezone and currency is this project configured with?"
    * "What features are enabled for this project?"
  </Accordion>

  <Accordion title="create_project">
    Create a new SegmentStream project with External BigQuery. Auto-resolves the billing account and creates a service account. Returns `projectId` and `serviceAccountEmail`.

    **Parameters:**

    | Name           | Type   | Required | Description                                                          |
    | -------------- | ------ | -------- | -------------------------------------------------------------------- |
    | `project_name` | string | Yes      | Project name, typically the website domain (e.g., `example.com`)     |
    | `timezone`     | string | Yes      | IANA timezone identifier (e.g., `Europe/London`, `America/New_York`) |
    | `currency`     | string | Yes      | ISO 4217 currency code (e.g., `USD`, `EUR`, `GBP`)                   |
    | `session_id`   | string | Yes      | Session ID returned by `analyze_request`                             |

    **Returns:** Object with `projectId` and `serviceAccountEmail`.

    **Example prompts:**

    * "Create a new project for example.com in the US Eastern timezone with USD currency"
    * "Set up a new SegmentStream project for my website"
  </Accordion>

  <Accordion title="update_project">
    Update project settings: name, timezone, or currency. Only pass the fields you want to change.

    **Parameters:**

    | Name           | Type   | Required | Description                              |
    | -------------- | ------ | -------- | ---------------------------------------- |
    | `project_id`   | string | Yes      | The project ID                           |
    | `project_name` | string | No       | New project name                         |
    | `timezone`     | string | No       | IANA timezone identifier                 |
    | `currency`     | string | No       | ISO 4217 currency code                   |
    | `session_id`   | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Updated project object.

    **Example prompts:**

    * "Change the project timezone to Europe/Berlin"
    * "Update the project currency to EUR"
    * "Rename the project to newsite.com"
  </Accordion>

  <Accordion title="get_current_user">
    Get the authenticated user's profile: id, name, email, and role.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** User profile object with id, name, email, and role.

    **Example prompts:**

    * "Who am I logged in as?"
    * "What role do I have?"
  </Accordion>

  <Accordion title="get_project_members">
    Get project members: id, name, email, role. Returns admins, viewers, and owners.

    **Parameters:**

    | Name         | Type   | Required | Description    |
    | ------------ | ------ | -------- | -------------- |
    | `project_id` | string | Yes      | The project ID |

    **Returns:** Array of member objects with id, name, email, and role.

    **Example prompts:**

    * "Who has access to this project?"
    * "List all project members and their roles"
  </Accordion>

  <Accordion title="invite_teammate">
    Invite a teammate to collaborate on a SegmentStream project. The teammate receives an email with context about what help is needed.

    **Parameters:**

    | Name             | Type   | Required | Description                                                  |
    | ---------------- | ------ | -------- | ------------------------------------------------------------ |
    | `email`          | string | Yes      | Email address of the teammate to invite                      |
    | `project_id`     | string | Yes      | The project ID to invite the teammate to                     |
    | `initial_prompt` | string | Yes      | Contextual message explaining what help is needed            |
    | `role`           | string | No       | Role for the invited teammate: `admin` (default) or `viewer` |
    | `session_id`     | string | Yes      | Session ID returned by `analyze_request`                     |

    **Returns:** Confirmation of the invitation.

    **Example prompts:**

    * "Invite [john@example.com](mailto:john@example.com) to help connect BigQuery"
    * "Add my colleague as a viewer on this project"
  </Accordion>
</AccordionGroup>

## Data sources

Tools for connecting, inspecting, and managing advertising platforms and their import status.

<AccordionGroup>
  <Accordion title="list_data_sources">
    List all data sources for a SegmentStream project.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `project_id` | string | Yes      | The project ID                           |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of data source objects.

    **Example prompts:**

    * "What ad platforms are connected to this project?"
    * "Show me all data sources"
    * "Which data sources are enabled?"
  </Accordion>

  <Accordion title="get_data_source">
    Get a single data source with details: id, name, type, `isEnabled`, `isAuthenticated`, options, `authMeta`, and workflow status.

    **Parameters:**

    | Name             | Type   | Required | Description                              |
    | ---------------- | ------ | -------- | ---------------------------------------- |
    | `data_source_id` | string | Yes      | The data source ID                       |
    | `session_id`     | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Full data source configuration object.

    **Example prompts:**

    * "Show me the configuration of the Facebook data source"
    * "Is the Google Ads data source authenticated?"
  </Accordion>

  <Accordion title="get_data_source_logs">
    Get import logs for a data source: phase, `startedAt`, `fillDate`, status, errors, and message.

    **Parameters:**

    | Name             | Type   | Required | Description                              |
    | ---------------- | ------ | -------- | ---------------------------------------- |
    | `project_id`     | string | Yes      | The project ID                           |
    | `data_source_id` | string | Yes      | The data source ID                       |
    | `session_id`     | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of import log entries with phase, timestamps, status, and error details.

    **Example prompts:**

    * "Show me the recent import logs for our Facebook data source"
    * "Are there any import errors for Google Ads?"
    * "When was the last successful import for this data source?"
  </Accordion>

  <Accordion title="list_available_data_sources">
    List all supported data source types with their display name, auth method (`oauth2` or `api_key`), and category (`analytics`, `advertising`, `crm`).

    **Parameters:** None

    **Returns:** Array of supported data source types with display name, auth method, and category.

    **Example prompts:**

    * "What ad platforms does SegmentStream support?"
    * "Which data sources use OAuth for authentication?"
    * "Show me all available CRM data sources"
  </Accordion>

  <Accordion title="connect_data_source">
    Connect a data source to a project. Multi-step flow: call repeatedly — first returns an auth URL, then configuration fields, then connects. Pass options progressively as the user provides them.

    **Parameters:**

    | Name                 | Type   | Required | Description                                                                                                |
    | -------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------- |
    | `project_id`         | string | Yes      | The project ID                                                                                             |
    | `type`               | string | Yes      | Data source type. Use display names: `Google Analytics 4`, `Google Ads`, `Meta Ads`, etc.                  |
    | `options`            | object | No       | Configuration options collected so far. Pass previous options plus the user's selection for the next field |
    | `storage_preference` | string | No       | Only for GA4 when no BigQuery Link exists: `managed` or `bring_your_own`                                   |
    | `session_id`         | string | Yes      | Session ID returned by `analyze_request`                                                                   |

    **Returns:** Next step in the connection flow (auth URL, configuration fields, or connection confirmation).

    **Example prompts:**

    * "Connect Google Ads to this project"
    * "Add Meta Ads as a data source"
    * "Set up a Google Analytics 4 connection"
  </Accordion>

  <Accordion title="disconnect_data_source">
    Disconnect a data source by clearing its credentials. Resets it to unauthenticated state so you can reconnect via `connect_data_source`. Use when: wrong account selected, insufficient OAuth scopes, or broken connection state.

    **Parameters:**

    | Name             | Type   | Required | Description                              |
    | ---------------- | ------ | -------- | ---------------------------------------- |
    | `data_source_id` | string | Yes      | The ID of the data source to disconnect  |
    | `session_id`     | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Confirmation that credentials were cleared.

    **Example prompts:**

    * "Disconnect the Google Ads data source so I can reconnect with a different account"
    * "Reset the Facebook data source connection"
  </Accordion>

  <Accordion title="connect_bigquery">
    Connect BigQuery to a SegmentStream project. Progressive multi-step flow: may return `configure` (select GCP project, location, or dataset), `grant_access` (service account needs permissions), or `connected` (done). Pass selections back via parameters.

    **Parameters:**

    | Name             | Type   | Required | Description                                                                                                              |
    | ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
    | `project_id`     | string | Yes      | SegmentStream project ID                                                                                                 |
    | `gcp_project_id` | string | No       | Google Cloud project ID where SegmentStream will store its BigQuery dataset                                              |
    | `location`       | string | No       | BigQuery dataset location (e.g., `US`, `EU`, `us-central1`). Should match the GA4 BigQuery export location if one exists |
    | `dataset_id`     | string | No       | BigQuery dataset ID for SegmentStream data. Defaults to `segmentstream` if omitted                                       |
    | `session_id`     | string | Yes      | Session ID returned by `analyze_request`                                                                                 |

    **Returns:** Next step in the connection flow (`configure`, `grant_access`, or `connected`).

    **Example prompts:**

    * "Connect BigQuery to my project"
    * "Set up BigQuery with my GCP project my-project-123 in the EU region"
  </Accordion>
</AccordionGroup>

## Conversions

Tools for creating, updating, and inspecting conversion definitions, statistics, and geographic breakdowns.

<AccordionGroup>
  <Accordion title="list_conversions">
    List all conversions for a project. Returns id, name, type (`online_purchase`, `online_event`, `sql`, `combined`, `probabilistic`), counting behavior, and key configuration.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `project_id` | string | Yes      | The project ID                           |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of conversion objects.

    **Example prompts:**

    * "What conversions are configured in this project?"
    * "List all active conversions"
    * "Show me the conversion IDs I need for reporting"
  </Accordion>

  <Accordion title="get_conversion">
    Get a single conversion with full configuration including type (`online_purchase`/`online_event`/`sql`), counting behavior, matching conditions, custom SQL, audiences, and combined conversions.

    **Parameters:**

    | Name            | Type   | Required | Description                              |
    | --------------- | ------ | -------- | ---------------------------------------- |
    | `conversion_id` | string | Yes      | The conversion ID                        |
    | `session_id`    | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Full conversion configuration object.

    **Example prompts:**

    * "Show me how the Purchase conversion is configured"
    * "What matching conditions does this conversion use?"
    * "Show me the SQL for this custom conversion"
  </Accordion>

  <Accordion title="create_conversion">
    Create a conversion. Choose type based on data source: `online_purchase` for tracked website purchases, `online_event` for tracked website events like sign-ups or form fills (requires `matching_conditions`), `sql` for conversions from custom SQL joining external data like CRM (requires `custom_sql`). Before setting matching conditions, use `list_filter_options` and `query_filter_option_values` (with `tool: "create_conversion"`) to discover available fields and values.

    **Parameters:**

    | Name                  | Type   | Required | Description                                                                            |
    | --------------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
    | `project_id`          | string | Yes      | The SegmentStream project ID                                                           |
    | `name`                | string | Yes      | Conversion name (e.g., `Purchase`, `Lead`, `Sign up`)                                  |
    | `type`                | string | Yes      | Conversion type: `online_purchase`, `online_event`, or `sql`                           |
    | `matching_conditions` | object | No       | Required for `online_event`. Conditions defining which events count as this conversion |
    | `custom_sql`          | string | No       | Required for `sql` type. BigQuery SQL query defining the conversion                    |
    | `counting`            | string | No       | `every_occurrence` (default) or `once_per_user`                                        |
    | `counting_window`     | number | No       | Days. Only used when counting is `once_per_user` (default 7)                           |
    | `value_type`          | string | No       | `none` (default), `event_value`, or `fixed` (`online_event` only)                      |
    | `value`               | number | No       | Fixed conversion value. Only when `value_type` is `fixed`                              |
    | `adjustment_window`   | number | No       | Refund adjustment window in days (`online_purchase` only)                              |
    | `session_id`          | string | Yes      | Session ID returned by `analyze_request`                                               |

    **Returns:** Created conversion object.

    **Example prompts:**

    * "Create a Purchase conversion"
    * "Add a Sign Up conversion that tracks the sign\_up event"
    * "Create a SQL conversion for CRM leads"
  </Accordion>

  <Accordion title="update_conversion">
    Update a conversion. Fetches current configuration and merges your changes. Only pass the fields you want to change. Works for all conversion types.

    **Parameters:**

    | Name                  | Type   | Required | Description                                               |
    | --------------------- | ------ | -------- | --------------------------------------------------------- |
    | `conversion_id`       | string | Yes      | The conversion ID to update                               |
    | `name`                | string | No       | New conversion name                                       |
    | `matching_conditions` | object | No       | Updated matching conditions (`online_event` only)         |
    | `custom_sql`          | string | No       | Updated SQL query (`sql` type only)                       |
    | `counting`            | string | No       | `every_occurrence` or `once_per_user`                     |
    | `counting_window`     | number | No       | Days. Only when counting is `once_per_user`               |
    | `value_type`          | string | No       | `none`, `event_value`, or `fixed` (`online_event` only)   |
    | `value`               | number | No       | Fixed conversion value                                    |
    | `description`         | string | No       | Conversion description                                    |
    | `adjustment_window`   | number | No       | Refund adjustment window in days (`online_purchase` only) |
    | `session_id`          | string | Yes      | Session ID returned by `analyze_request`                  |

    **Returns:** Updated conversion object.

    **Example prompts:**

    * "Rename the Purchase conversion to Online Purchase"
    * "Change the counting to once per user with a 30-day window"
    * "Update the SQL for this CRM conversion"
  </Accordion>

  <Accordion title="list_conversion_fields">
    List available fields for a specific conversion. Returns default fields (present on every conversion) and custom fields (CRM/dynamic — defined by the conversion SQL, vary per conversion). Use this before `query_conversion_records` to discover what data is available.

    **Parameters:**

    | Name            | Type   | Required | Description                              |
    | --------------- | ------ | -------- | ---------------------------------------- |
    | `project_id`    | string | Yes      | The SegmentStream project ID             |
    | `conversion_id` | string | Yes      | The conversion ID to list fields for     |
    | `session_id`    | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Default and custom fields available for the conversion.

    **Example prompts:**

    * "What fields are available for the Lead conversion?"
    * "Show me the CRM fields I can query for this conversion"
    * "List conversion record fields"
  </Accordion>

  <Accordion title="get_conversion_statistics">
    Get conversion statistics including `totalConversions`, `totalSessions`, `totalValues`, visitors, `conversionsHistory` (per date), and `exportsHistory`.

    **Parameters:**

    | Name                | Type   | Required | Description                              |
    | ------------------- | ------ | -------- | ---------------------------------------- |
    | `project_id`        | string | Yes      | The project ID                           |
    | `conversion_id`     | string | Yes      | The conversion ID                        |
    | `date_from`         | string | No       | Start date in `YYYY-MM-DD` format        |
    | `date_to`           | string | No       | End date in `YYYY-MM-DD` format          |
    | `chart_granularity` | string | No       | `DAY` or `HOUR`                          |
    | `session_id`        | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Statistics object with totals and per-date history.

    **Example prompts:**

    * "How many purchases happened last month?"
    * "Show me the daily conversion trend for the past 30 days"
    * "What is the total conversion value this quarter?"
  </Accordion>

  <Accordion title="get_conversions_by_country">
    Get conversions grouped by country for a given conversion and date range.

    **Parameters:**

    | Name            | Type   | Required | Description                              |
    | --------------- | ------ | -------- | ---------------------------------------- |
    | `conversion_id` | string | Yes      | The conversion ID                        |
    | `project_id`    | string | Yes      | The project ID                           |
    | `start_date`    | string | Yes      | Start date in `YYYY-MM-DD` format        |
    | `end_date`      | string | Yes      | End date in `YYYY-MM-DD` format          |
    | `session_id`    | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Conversions grouped by country.

    **Example prompts:**

    * "Which countries had the most purchases last month?"
    * "Break down lead conversions by country for Q4"
  </Accordion>

  <Accordion title="query_conversion_records">
    Query individual conversion-level records. Returns one row per conversion event with selected fields — use for any question about specific customers, contacts, CRM data, or conversion-level attributes. Use `list_conversion_fields` first to discover available fields. When `attribution_id` is provided, filters support report dimensions (`channel`, `campaign_name`). For aggregated performance analytics (ROAS, CPA, conversion counts by dimension), use `run_report` instead.

    **Parameters:**

    | Name             | Type   | Required | Description                                                         |
    | ---------------- | ------ | -------- | ------------------------------------------------------------------- |
    | `project_id`     | string | Yes      | The SegmentStream project ID                                        |
    | `conversion_id`  | string | Yes      | The conversion ID to query records for                              |
    | `date_range`     | object | Yes      | Date range with `from` and `to` in `YYYY-MM-DD`                     |
    | `fields`         | array  | Yes      | Fields to return — use names from `list_conversion_fields` directly |
    | `attribution_id` | string | No       | Attribution model ID — enables channel and campaign filtering       |
    | `filter`         | object | No       | Filter expression (same format as `run_report`)                     |
    | `order_by`       | array  | No       | Sort order with `field` and `direction`                             |
    | `format`         | string | No       | `json` (default) or `csv` for compact tabular output                |
    | `limit`          | number | No       | Max rows (default 500, max 1000)                                    |
    | `offset`         | number | No       | Row offset for pagination                                           |
    | `session_id`     | string | Yes      | Session ID returned by `analyze_request`                            |

    **Returns:** Individual conversion records with the requested fields.

    **Example prompts:**

    * "Show me the last 50 leads with their email and source"
    * "List all conversions from Generic Search last month with CRM fields"
    * "Which customers converted from Meta Ads this week?"
  </Accordion>
</AccordionGroup>

## Attribution models

Tools for inspecting and managing attribution model configurations.

<AccordionGroup>
  <Accordion title="list_attribution_models">
    List all attribution models for a project with their id, name, algorithm, `attributionWindow`, adjustment, filter, dimension, and `isDisabled`.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `project_id` | string | Yes      | The project ID                           |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of attribution model objects.

    **Example prompts:**

    * "What attribution models are available?"
    * "Which attribution model is the default?"
    * "Show me all attribution model IDs"
  </Accordion>

  <Accordion title="get_attribution_model">
    Get a single attribution model with full details including calibration, dimension values, and self-reported attribution settings.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `id`         | string | Yes      | The attribution model ID                 |
    | `project_id` | string | Yes      | The project ID                           |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Full attribution model configuration object.

    **Example prompts:**

    * "Show me the configuration of the Multi-Touch attribution model"
    * "What is the attribution window for the Last Click model?"
    * "Does this model use self-reported attribution?"
  </Accordion>

  <Accordion title="create_attribution_model">
    Create a new attribution model. After save, SegmentStream automatically runs a 1-year backfill to populate attribution data — no follow-up call needed. The window is capped by the project's actual data.

    The `significant_touch_rule` (last-click only) defines which touches the engine treats as "significant" credit recipients in the cascade: (1) credit goes to the most recent touch matching the rule, (2) if no touch matches, credit falls back to the most recent non-direct touch, (3) if the journey has no non-direct touches, credit falls back to direct.

    **Parameters:**

    | Name                          | Type    | Required | Description                                                                                                                                                              |
    | ----------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `project_id`                  | string  | Yes      | The project ID                                                                                                                                                           |
    | `name`                        | string  | Yes      | Human-readable model name                                                                                                                                                |
    | `algorithm`                   | string  | Yes      | `first_click` or `last_click`                                                                                                                                            |
    | `attribution_window`          | number  | No       | Window in days (default `90`, `null` disables the cap)                                                                                                                   |
    | `significant_touch_rule`      | object  | No       | Boolean filter AST, only valid for `last_click`. `{ and: [...] } \| { or: [...] } \| { option, operator, value }`. Use `list_filter_options` for allowed `option` values |
    | `self_reported_reattribution` | boolean | No       | Whether the model applies self-reported reattribution (default `true`)                                                                                                   |
    | `session_id`                  | string  | Yes      | Session ID returned by `analyze_request`                                                                                                                                 |

    **Returns:** Created attribution model in the same shape as `get_attribution_model`.

    **Example prompts:**

    * "Create a last-click attribution model with a 30-day window"
    * "Add a first-click model called Acquisition"
    * "Create a last paid non-brand attribution model"
  </Accordion>

  <Accordion title="update_attribution_model">
    Update an attribution model. Supports partial updates of name, attribution window, significant-touch rule, and self-reported reattribution. After save, SegmentStream automatically reruns the 1-year backfill.

    **Parameters:**

    | Name                          | Type    | Required | Description                                                                            |
    | ----------------------------- | ------- | -------- | -------------------------------------------------------------------------------------- |
    | `project_id`                  | string  | Yes      | The project ID                                                                         |
    | `id`                          | string  | Yes      | The attribution model ID                                                               |
    | `name`                        | string  | No       | Updated model name                                                                     |
    | `attribution_window`          | number  | No       | Updated window in days; `null` disables the cap                                        |
    | `significant_touch_rule`      | object  | No       | Updated boolean filter AST (last-click only). Same shape as `create_attribution_model` |
    | `self_reported_reattribution` | boolean | No       | Toggle self-reported reattribution                                                     |
    | `session_id`                  | string  | Yes      | Session ID returned by `analyze_request`                                               |

    **Returns:** Updated attribution model in the same shape as `get_attribution_model`.

    **Example prompts:**

    * "Change the attribution window of the Last Click model to 60 days"
    * "Update the significant-touch rule to exclude direct traffic"
    * "Disable self-reported reattribution on this model"
  </Accordion>
</AccordionGroup>

## Reports and analytics

Tools for querying campaign performance data — the primary way to pull metrics from SegmentStream.

<AccordionGroup>
  <Accordion title="run_report">
    Run an aggregated report query with proper attribution. Returns grouped metrics (conversions, ROAS, CPA, cost) by dimensions (channel, campaign, country). This is the primary tool for performance analytics. For individual conversion-level data, use `query_conversion_records`. Use `query_filter_option_values` to discover exact filter values. Use `format: "csv"` for fewer tokens.

    All query options live under a single `settings` object — same shape `get_saved_report` returns and `save_report` accepts. To execute a saved report, pass `saved_report_id` and use `settings` as a partial override (omit a field to keep saved, arrays replace entirely, explicit `null` clears).

    **Parameters:**

    | Name                              | Type            | Required    | Description                                                                                                                                                                                                                                                                                                                                                                                                                    |
    | --------------------------------- | --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `project_id`                      | string          | Yes         | The project ID                                                                                                                                                                                                                                                                                                                                                                                                                 |
    | `saved_report_id`                 | string          | No          | If provided, loads the saved report as the base; `settings` becomes a partial override                                                                                                                                                                                                                                                                                                                                         |
    | `settings`                        | object          | Conditional | Full settings (when no `saved_report_id`) or override (when `saved_report_id`). See nested fields below                                                                                                                                                                                                                                                                                                                        |
    | `settings.date_range`             | object          | Conditional | Primary date range. `{ interval, from, to }`. `interval` defaults to `custom`; named intervals (`last_7_days`, `last_30_days`, etc.) resolve dates server-side                                                                                                                                                                                                                                                                 |
    | `settings.comparison_date_range`  | object          | No          | Comparison date range for period-over-period analysis. Supports relative intervals (`preceding_period`, `same_period_last_year`)                                                                                                                                                                                                                                                                                               |
    | `settings.dimensions`             | array of string | No          | Dimensions to group by (`campaign_name`, `ad_platform`, `channel`, `country`, etc.). `channel` is a built-in alias for the Channel grouped dimension                                                                                                                                                                                                                                                                           |
    | `settings.metrics`                | array of string | No          | Bare snake\_case metric names — server infers traffic vs. conversion. Traffic: `cost`, `clicks`, `impressions`, `sessions`, `users`, `cpc`, `cpm`, `ctr`. Conversion: `conversions`, `conversion_value`, `converted_users`, `conversion_rate`, `cpa`, `roas`, `aov`, plus `*_by_conv_time` and `*_incl_projected` variants. Never prefix with the AC id — pass once and it fans out to every entry in `attributed_conversions` |
    | `settings.attributed_conversions` | array           | Conditional | `[{ id, conversion_id, attribution_id }]`. Required when conversion metrics are requested. Per-AC output columns are named `<id>:<metric>`                                                                                                                                                                                                                                                                                     |
    | `settings.filter`                 | object          | No          | Filter expression. Boolean AST: `{ and: [...] } \| { or: [...] } \| { option, operator, value }`. Operators: `equals`, `not_equals`, `contains`, `not_contains`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `is_set`, `not_set`                                                                                                                                                                                                 |
    | `settings.order_by`               | array           | No          | `[{ metric, direction, scope?, attributed_conversion_id? }]`. `scope` (`first_interval`/`second_interval`/`diff`) is only meaningful with a comparison date range                                                                                                                                                                                                                                                              |
    | `limit`                           | number          | No          | Max rows (default 1000, max 1000)                                                                                                                                                                                                                                                                                                                                                                                              |
    | `offset`                          | number          | No          | Row offset for pagination                                                                                                                                                                                                                                                                                                                                                                                                      |
    | `time_machine_date`               | string          | No          | `YYYY-MM-DD` snapshot of tracked conversions and ML predictions as of that date. Must be a Sunday for projections                                                                                                                                                                                                                                                                                                              |
    | `format`                          | string          | No          | `json` (default) or `csv`                                                                                                                                                                                                                                                                                                                                                                                                      |
    | `session_id`                      | string          | Yes         | Session ID returned by `analyze_request`                                                                                                                                                                                                                                                                                                                                                                                       |

    **Returns:** Table data with dimensions and metrics for each row, plus totals (and `comparison_totals` when `comparison_date_range` is set).

    **Example prompts:**

    * "Show me the top 10 campaigns by cost for the last 30 days"
    * "What is the ROAS by ad platform for last month?"
    * "Give me a breakdown of conversions by source/medium and country"
    * "Compare campaign performance between this month and last month"
    * "Run my Performance Overview saved report with last\_60\_days instead"
  </Accordion>

  <Accordion title="run_report_timeseries">
    Run a timeseries (chart) report — per-date metric values over a date range. Useful for visualizing trends and spotting anomalies. To run the timeseries view of a saved report, pass `saved_report_id`; the saved chart config (`chart.date_granularity`, `chart.metrics`) becomes the base and `settings` is a partial override.

    **Parameters:**

    | Name                              | Type            | Required    | Description                                                                                              |
    | --------------------------------- | --------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
    | `project_id`                      | string          | Yes         | The project ID                                                                                           |
    | `saved_report_id`                 | string          | No          | If provided, loads the saved report's chart config as the base                                           |
    | `settings`                        | object          | Conditional | Same nested shape as `run_report` settings (no `comparison_date_range`) plus a nested `chart` sub-object |
    | `settings.date_range`             | object          | Conditional | `{ interval, from, to }`                                                                                 |
    | `settings.dimensions`             | array of string | No          | Dimensions to group by                                                                                   |
    | `settings.attributed_conversions` | array           | Conditional | Required when conversion metrics are plotted                                                             |
    | `settings.filter`                 | object          | No          | Filter expression — same shape as `run_report`                                                           |
    | `settings.chart.date_granularity` | string          | No          | `day` (default), `hour`, `week`, or `month`                                                              |
    | `settings.chart.metrics`          | array           | No          | Metrics to plot. Bare strings or `{ metric, attributed_conversion_id }` entries pinned to a specific AC  |
    | `time_machine_date`               | string          | No          | `YYYY-MM-DD` snapshot date                                                                               |
    | `session_id`                      | string          | Yes         | Session ID returned by `analyze_request`                                                                 |

    **Returns:** Per-date data points for the requested metrics.

    **Example prompts:**

    * "Show me the daily cost trend for the past 30 days"
    * "Plot weekly conversions over the last 3 months"
    * "Chart the ROAS trend by week for Facebook campaigns"
  </Accordion>

  <Accordion title="list_saved_reports">
    List all saved reports for a project, each with full settings (dimensions, metrics, filter, date range, chart config). Match user intent against name + settings in place — no second fetch needed. When an entry matches, run it via `run_report` (or `run_report_timeseries`) with `saved_report_id`.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `project_id` | string | Yes      | The project ID                           |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of saved reports, each with `id`, `name`, `project_id`, `url` (admin panel link), and `settings`.

    **Example prompts:**

    * "What reports are saved in this project?"
    * "Find the saved report for channel performance"
    * "Show me all saved reports and pick the one that matches our weekly review"
  </Accordion>

  <Accordion title="get_saved_report">
    Get a single saved report by id. Returns id, name, project\_id, url (admin panel link), and settings — date range, dimensions, metrics, attributed\_conversions, filter, order\_by, chart config. The returned settings can be passed directly to `save_report` (to duplicate or update) or to `run_report` / `run_report_timeseries` (to execute with overrides). Typical flow: `get → mutate → save` or `get → mutate → run`.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `project_id` | string | Yes      | The project ID                           |
    | `report_id`  | string | Yes      | The saved report ID                      |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Full saved report (`id`, `name`, `project_id`, `url`, `settings`).

    **Example prompts:**

    * "Show me the configuration of the Performance Overview report"
    * "What dimensions and metrics does this saved report use?"
  </Accordion>

  <Accordion title="save_report">
    Create, update, or duplicate a saved report. Upsert semantics — omit `id` to CREATE (server generates a UUID), pass an existing `id` to UPDATE. To DUPLICATE, call `get_saved_report`, mutate the returned settings, and call `save_report` WITHOUT the id. Returns the saved report including a direct URL to the admin panel. The `settings` shape is identical to what `get_saved_report` returns and `run_report` accepts. If `chart.metrics` is set but `chart.rows` is omitted, a default Total row is auto-populated so the chart renders.

    **Parameters:**

    | Name         | Type   | Required | Description                                                                                                                                                                                                                                        |
    | ------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `project_id` | string | Yes      | The project ID                                                                                                                                                                                                                                     |
    | `id`         | string | No       | Existing report id to update. Omit to create.                                                                                                                                                                                                      |
    | `name`       | string | Yes      | Human-readable report name                                                                                                                                                                                                                         |
    | `settings`   | object | Yes      | Full report settings — same shape as `get_saved_report` returns. Includes `date_range`, `dimensions`, `metrics`, `attributed_conversions`, `filter`, `order_by`, optional `chart`, optional `percentage_metrics` / `percentage_difference_metrics` |
    | `session_id` | string | No       | Session ID returned by `analyze_request`                                                                                                                                                                                                           |

    **Returns:** Saved report with `id`, `name`, `project_id`, `url`, `settings`.

    **Example prompts:**

    * "Save this report as 'Weekly channel review'"
    * "Duplicate the Performance Overview report and add a country dimension"
    * "Update the saved report to use last\_30\_days"
  </Accordion>

  <Accordion title="share_artifact">
    Upload an HTML artifact to shared storage and return a shareable URL. Use for sharing reports, dashboards, and analysis results.

    **Parameters:**

    | Name           | Type   | Required | Description                                    |
    | -------------- | ------ | -------- | ---------------------------------------------- |
    | `html_content` | string | Yes      | The full HTML content of the artifact to share |
    | `title`        | string | Yes      | Human-readable title for the artifact          |
    | `session_id`   | string | Yes      | Session ID returned by `analyze_request`       |

    **Returns:** Shareable URL for the uploaded artifact.

    **Example prompts:**

    * "Share this report as a link"
    * "Generate a shareable URL for this dashboard"
  </Accordion>
</AccordionGroup>

## Filters

Tools for discovering valid filter fields and their values. Used before building filter expressions for `run_report`, `query_conversion_records`, conversion matching conditions, grouped dimension rules, and attribution model significant-touch rules.

<AccordionGroup>
  <Accordion title="list_filter_options">
    List available filter fields for a specific tool. Pass the tool name that needs filters — the response includes only fields valid for that tool.

    * For `create_conversion` / `update_conversion`: returns GA4 field names (`event_name`, `items.item_category`, `event_params.*`, `geo.country`, etc.).
    * For `create_grouped_dimension` / `update_grouped_dimension`: returns base dimensions only (`campaign_name`, `ad_platform`, `country`, etc. — no grouped dimensions).
    * For `run_report` / `create_attribution_model` / `update_attribution_model`: returns base dimensions and grouped dimensions (Channel, etc.).

    **Parameters:**

    | Name         | Type   | Required | Description                                                                                          |
    | ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
    | `project_id` | string | Yes      | The project ID                                                                                       |
    | `tool`       | string | Yes      | Which tool needs filter options (e.g. `run_report`, `create_conversion`, `create_grouped_dimension`) |

    **Returns:** Array of filter field definitions appropriate for the requested tool.

    **Example prompts:**

    * "What fields can I filter on in run\_report?"
    * "List GA4 fields I can use in a conversion matching condition"
    * "Show me the base dimensions available when defining a Channel rule"
  </Accordion>

  <Accordion title="query_filter_option_values">
    Query distinct values for a filter option. Pass the tool name and field — returns actual values from the project data. Use after `list_filter_options` to discover what values exist for a specific option.

    * For conversion tools: accepts GA4 field names (`event_name`, `items.item_category`, `event_params.subscription`, `geo.country`).
    * For dimensions (`run_report`, `create_grouped_dimension`): queries session-level data and grouped dimension groups (e.g. `channel`).

    **Parameters:**

    | Name         | Type   | Required | Description                                                                                                                            |
    | ------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
    | `project_id` | string | Yes      | The project ID                                                                                                                         |
    | `tool`       | string | Yes      | Which tool needs these values (determines the data source to query)                                                                    |
    | `field`      | string | Yes      | The field to query values for (e.g. `campaign_name`, `ad_platform`, `country`, `event.name`, `channel`, or a `custom_dimension_*` key) |
    | `query`      | string | No       | Substring filter (case-insensitive). Pass ONE keyword                                                                                  |

    **Returns:** Array of available values for the specified field.

    **Example prompts:**

    * "What campaign names are available in this project?"
    * "List all ad platform values"
    * "Show me the values of the Channel dimension"
    * "What values exist for the event\_params.subscription field?"
  </Accordion>
</AccordionGroup>

## User journey

Tools for tracing individual user paths and attribution credit distribution.

<AccordionGroup>
  <Accordion title="get_user_journey">
    Query the user journey for a date range, returning all sessions with attribution credits, conversions, audience memberships, and user keys. Filter by `anonymous_id` or `user_id`. Useful for debugging attribution and understanding individual user paths.

    **Parameters:**

    | Name                             | Type   | Required | Description                                            |
    | -------------------------------- | ------ | -------- | ------------------------------------------------------ |
    | `project_id`                     | string | Yes      | The project ID                                         |
    | `params.date_from`               | string | Yes      | Start date (`YYYY-MM-DD`)                              |
    | `params.date_to`                 | string | Yes      | End date (`YYYY-MM-DD`)                                |
    | `params.attributed_conversions`  | array  | Yes      | Array of `{id, conversion_id, attribution_id}` objects |
    | `params.conversion_internal_ids` | array  | Yes      | Conversion internal IDs to include                     |
    | `params.selected_anonymous_id`   | string | No       | Filter to a specific anonymous ID                      |
    | `params.selected_user_id`        | string | No       | Filter to a specific user ID                           |
    | `session_id`                     | string | Yes      | Session ID returned by `analyze_request`               |

    **Returns:** Sessions with attribution credits, conversions, audience memberships, and user keys.

    **Example prompts:**

    * "Show me the user journey for anonymous ID `abc123` over the last 30 days"
    * "What touchpoints led to the last conversion for user `user@example.com`?"
    * "Trace the journey for this anonymous ID and show attribution credits"
  </Accordion>

  <Accordion title="debug_user_journey">
    Get the generated BigQuery SQL and query parameters for a user journey query without executing it. Useful for debugging attribution SQL.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `project_id` | string | Yes      | The project ID                           |
    | `params`     | object | Yes      | Same parameters as `get_user_journey`    |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** BigQuery SQL string and query parameters.

    **Example prompts:**

    * "Show me the SQL behind this user journey query"
    * "Debug the user journey query for this anonymous ID"
  </Accordion>
</AccordionGroup>

## BigQuery

Direct SQL access to your project's BigQuery dataset. Only available for projects with their own Google BigQuery (bring-your-own). Not available for SegmentStream-managed projects — use `run_report`, `query_conversion_records`, and `query_filter_option_values` instead.

<AccordionGroup>
  <Accordion title="bigquery_execute_sql">
    Execute a read-only BigQuery SQL query against the project's dataset. Tables can be referenced without full qualification (e.g., `hitsSet` instead of `project.dataset.hitsSet`). Best for: raw event data exploration, PII/CRM field lookups, schema inspection, and custom analysis the report API cannot express. For questions involving channel attribution, campaign performance, or conversion metrics, prefer `run_report` — it uses the attribution engine automatically.

    **Parameters:**

    | Name         | Type   | Required | Description                                                                            |
    | ------------ | ------ | -------- | -------------------------------------------------------------------------------------- |
    | `project_id` | string | Yes      | The SegmentStream project ID (use `list_active_projects` to find it)                   |
    | `query`      | string | Yes      | The BigQuery SQL query to execute. Tables can be referenced without full qualification |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request`                                               |

    **Returns:** Query results as JSON.

    **Example prompts:**

    * "Run a query to count sessions by country for last week"
    * "Show me the schema of the sessions table"
    * "Query the raw events table for the last 24 hours"
    * "How many unique users visited the site yesterday?"
  </Accordion>

  <Accordion title="bigquery_get_table_schema">
    Get the schema (column names, types, modes) of a BigQuery table via the API — no SQL needed. Use this before writing SQL queries to verify table structure and available columns. Returns `null` if the table does not exist. Use `list_active_projects` to find the project ID.

    **Parameters:**

    | Name         | Type   | Required | Description                                                                                                                                                              |
    | ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `project_id` | string | Yes      | The SegmentStream project ID                                                                                                                                             |
    | `table_name` | string | Yes      | The table name within the project dataset (e.g., `hitsSet`, `conversions`, `attribution`, `cost_data`). Do not fully qualify — the project dataset is used automatically |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request`                                                                                                                                 |

    **Returns:** Array of column objects with name, type, and mode.

    **Example prompts:**

    * "What columns does the sessions table have?"
    * "Show me the schema for hitsSet"
    * "What fields are available in the conversions table?"
  </Accordion>
</AccordionGroup>

## Grouped dimensions

Tools for inspecting and managing grouped dimensions — categorizations that bucket base dimension values into named groups (e.g., the Channel dimension groups campaigns into "Paid Search", "Paid Social", "Organic Search").

<AccordionGroup>
  <Accordion title="list_grouped_dimensions">
    List all grouped dimensions for a project. Use the key in `run_report` dimensions or `get_grouped_dimension`. `channel` is a built-in alias for the Channel dimension.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `project_id` | string | Yes      | The project ID                           |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of grouped dimension objects with key, name, and type.

    **Example prompts:**

    * "What grouped dimensions are available?"
    * "List all dimension keys I can use in reports"
  </Accordion>

  <Accordion title="get_grouped_dimension">
    Get a grouped dimension with its groups and filter rules. Use key `channel` for the Channel dimension. Returns groups in evaluation order — each has a name and a filter using base dimensions like `ad_platform`, `campaign_name`, `utm_source`. Use this before `update_grouped_dimension` to see current groups.

    **Parameters:**

    | Name         | Type   | Required | Description                                |
    | ------------ | ------ | -------- | ------------------------------------------ |
    | `project_id` | string | Yes      | The project ID                             |
    | `key`        | string | Yes      | The grouped dimension key (e.g. `channel`) |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request`   |

    **Returns:** Full grouped dimension object with groups and filters.

    **Example prompts:**

    * "Show me the Channel dimension groups"
    * "How is this grouped dimension configured?"
  </Accordion>

  <Accordion title="create_grouped_dimension">
    Create a new grouped dimension. Groups categorize traffic by assigning base dimension values to named buckets. Filters use base dimensions only (`ad_platform`, `campaign_name`, `campaign_type`, `utm_source`, `utm_medium`, `source_medium`, `country`, `device`, etc.). Use `query_filter_option_values` (with `tool: "create_grouped_dimension"`) to discover exact values before building group filter rules. If no groups are provided, all traffic goes to "Other".

    **Parameters:**

    | Name         | Type   | Required | Description                                                                                                                                                       |
    | ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `project_id` | string | Yes      | The project ID                                                                                                                                                    |
    | `name`       | string | Yes      | Display name for the new dimension (e.g. `Region`, `Product Category`)                                                                                            |
    | `groups`     | array  | No       | Each group has a `name` and `filter`. Groups are evaluated in order — first match wins. Traffic not matching any group falls into the auto-appended `Other` group |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request`                                                                                                                          |

    **Returns:** Object with `status: "created"`, `key`, `name`, and the list of group names.

    **Example prompts:**

    * "Create a Region grouped dimension with EMEA and North America groups"
    * "Add a Brand vs Non-Brand dimension"
  </Accordion>

  <Accordion title="update_grouped_dimension">
    Update a grouped dimension. For the Channel dimension (key `channel`), update groups that define how traffic is categorized. Each group has a `name` and a `filter`. Filters use base dimensions only. Groups are evaluated in order — first match wins. Put specific rules first, broad rules last. Traffic not matching any group goes to `Other` automatically.

    Filter shape — single rule: `{ "option": "ad_platform", "operator": "equals", "value": "Facebook" }`. Compound: `{ "or": [{ "option": "utm_source", "operator": "contains", "value": "chatgpt" }, { "option": "utm_source", "operator": "contains", "value": "perplexity" }] }`.

    <Warning>
      Full replacement — groups not included are permanently removed. Call `get_grouped_dimension` first to see current groups.
    </Warning>

    **Parameters:**

    | Name         | Type   | Required | Description                                                                                                                                                                       |
    | ------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `project_id` | string | Yes      | The project ID                                                                                                                                                                    |
    | `key`        | string | Yes      | Grouped dimension key. Use `channel` for the Channel dimension                                                                                                                    |
    | `name`       | string | No       | New display name for the dimension                                                                                                                                                |
    | `groups`     | array  | No       | Group definitions, evaluated in order. Each group has a `name` and `filter` (same boolean AST as `run_report` filters). Use `query_filter_option_values` to discover exact values |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request`                                                                                                                                          |

    **Returns:** Object with `status: "updated"`, `key`, `name`, list of channel names, and `catch_all: "Other"`.

    **Example prompts:**

    * "Add a TikTok Ads channel to the Channel dimension"
    * "Update the Channel dimension to include an Organic AI group"
    * "Rename the Brand Search group"
  </Accordion>
</AccordionGroup>

## Audiences

Tools for inspecting audience definitions and memberships.

<AccordionGroup>
  <Accordion title="list_audiences">
    List audiences for a project, optionally filtered by ML model or conversion. Returns id, name, `isForever`, filter, `membershipDurationDays`, and status for each audience.

    **Parameters:**

    | Name            | Type   | Required | Description                              |
    | --------------- | ------ | -------- | ---------------------------------------- |
    | `project_id`    | string | Yes      | The project ID                           |
    | `ml_model_id`   | string | No       | Filter audiences by ML model             |
    | `conversion_id` | string | No       | Filter audiences by conversion           |
    | `session_id`    | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of audience objects.

    **Example prompts:**

    * "What audiences are defined in this project?"
    * "List all audiences associated with the Purchase conversion"
  </Accordion>

  <Accordion title="get_audience">
    Get a single audience with full details including id, name, `projectId`, `isForever`, filter, `filterSql`, `membershipDurationDays`, status, `createdAt`, and `updatedAt`.

    **Parameters:**

    | Name          | Type   | Required | Description                              |
    | ------------- | ------ | -------- | ---------------------------------------- |
    | `audience_id` | string | Yes      | The audience ID                          |
    | `session_id`  | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Full audience configuration object.

    **Example prompts:**

    * "Show me the filter criteria for this audience"
    * "How long do users stay in this audience?"
  </Accordion>

  <Accordion title="query_audiences_by_client_id">
    Query audience memberships for a specific client (anonymous ID) within a date range. Returns `audienceId`, `audienceName`, `entryTime`, and `expirationTime` for each membership.

    **Parameters:**

    | Name           | Type   | Required | Description                                               |
    | -------------- | ------ | -------- | --------------------------------------------------------- |
    | `project_id`   | string | Yes      | The project ID                                            |
    | `anonymous_id` | string | Yes      | The anonymous client ID to query audience memberships for |
    | `from`         | string | Yes      | Start date (ISO date, e.g., `2025-01-01`)                 |
    | `to`           | string | Yes      | End date (ISO date, e.g., `2025-01-31`)                   |
    | `session_id`   | string | Yes      | Session ID returned by `analyze_request`                  |

    **Returns:** Array of audience membership objects with entry and expiration times.

    **Example prompts:**

    * "What audiences does anonymous ID `abc123` belong to?"
    * "Show me audience memberships for this user over the last 30 days"
  </Accordion>

  <Accordion title="get_audiences_inclusion">
    Get audience inclusion statistics for a project: per-audience inclusion count and percent, total inclusion, total percent, and `allUsers` count. Optionally filter by ML model.

    **Parameters:**

    | Name          | Type   | Required | Description                              |
    | ------------- | ------ | -------- | ---------------------------------------- |
    | `project_id`  | string | Yes      | The project ID                           |
    | `ml_model_id` | string | No       | Filter inclusion stats by ML model       |
    | `session_id`  | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Inclusion statistics with per-audience counts and percentages.

    **Example prompts:**

    * "What percentage of users are in each audience?"
    * "Show me audience inclusion statistics"
  </Accordion>
</AccordionGroup>

## Workflows

Tools for monitoring data processing workflows.

<AccordionGroup>
  <Accordion title="list_workflows">
    List recent workflows for a SegmentStream project.

    **Parameters:**

    | Name         | Type   | Required | Description                                        |
    | ------------ | ------ | -------- | -------------------------------------------------- |
    | `project_id` | string | Yes      | The project ID                                     |
    | `limit`      | number | No       | Maximum number of workflows to return (default 20) |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request`           |

    **Returns:** Array of workflow objects.

    **Example prompts:**

    * "Show me the recent workflows"
    * "What data processing jobs ran today?"
  </Accordion>

  <Accordion title="get_workflow_status">
    Get the status and details of a specific workflow, including data source logs and errors.

    **Parameters:**

    | Name          | Type   | Required | Description                              |
    | ------------- | ------ | -------- | ---------------------------------------- |
    | `workflow_id` | string | Yes      | The workflow ID                          |
    | `session_id`  | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Workflow status object with data source logs and error details.

    **Example prompts:**

    * "What is the status of this workflow?"
    * "Did this workflow complete successfully?"
    * "Show me any errors from the last workflow run"
  </Accordion>
</AccordionGroup>

## Cost data quality

Tools for monitoring advertising cost data accuracy.

<AccordionGroup>
  <Accordion title="get_cost_data_quality">
    Get cost data quality metrics: quality scores (total, 7-day, 1-day) and histogram. Optionally filter by data source and date range.

    **Parameters:**

    | Name             | Type   | Required | Description                              |
    | ---------------- | ------ | -------- | ---------------------------------------- |
    | `project_id`     | string | Yes      | The project ID                           |
    | `data_source_id` | number | No       | Scope results to a specific data source  |
    | `date_from`      | string | No       | Start date (`YYYY-MM-DD`)                |
    | `date_to`        | string | No       | End date (`YYYY-MM-DD`)                  |
    | `session_id`     | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Quality scores and histogram data.

    **Example prompts:**

    * "What is the cost data quality score for this project?"
    * "Show me the data quality for the Facebook data source"
    * "How has cost data quality changed over the last 30 days?"
  </Accordion>
</AccordionGroup>

## Identity graph

Tools for inspecting user identity stitching.

<AccordionGroup>
  <Accordion title="get_identity_graph_statistics">
    Get identity graph statistics including user stitching distribution, key combinations, and data completeness.

    **Parameters:**

    | Name                     | Type    | Required | Description                              |
    | ------------------------ | ------- | -------- | ---------------------------------------- |
    | `project_id`             | string  | Yes      | The project ID                           |
    | `conversion_internal_id` | string  | No       | Filter by internal conversion ID         |
    | `days_back`              | number  | No       | Number of days to look back              |
    | `use_users_v2`           | boolean | No       | Whether to use the users v2 engine       |
    | `session_id`             | string  | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Identity graph statistics object.

    **Example prompts:**

    * "Show me the identity graph statistics"
    * "How many users have cross-device stitching?"
    * "What is the user stitching distribution for the last 30 days?"
  </Accordion>
</AccordionGroup>

## Incidents

Tools for checking project health alerts.

<AccordionGroup>
  <Accordion title="list_incidents">
    List incidents for a project with optional filtering by status and pagination.

    **Parameters:**

    | Name                 | Type   | Required | Description                                            |
    | -------------------- | ------ | -------- | ------------------------------------------------------ |
    | `project_id`         | string | Yes      | The project ID                                         |
    | `status`             | string | No       | Filter by status: `Ok` or `Error`                      |
    | `limit`              | number | No       | Maximum number of incidents to return                  |
    | `offset`             | number | No       | Number of incidents to skip for pagination             |
    | `minimum_updated_at` | string | No       | Only return incidents updated after this ISO-8601 date |
    | `session_id`         | string | Yes      | Session ID returned by `analyze_request`               |

    **Returns:** Array of incident objects.

    **Example prompts:**

    * "Are there any active incidents?"
    * "Show me recent errors for this project"
    * "List all incidents from the last week"
  </Accordion>
</AccordionGroup>

## Classifiers (ML models)

Tools for inspecting ML-based classifiers used for conversion scoring.

<AccordionGroup>
  <Accordion title="list_classifiers">
    List all classifiers for a project with their configuration.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `project_id` | string | Yes      | The project ID                           |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of classifier objects.

    **Example prompts:**

    * "What ML classifiers are configured?"
    * "Show me the classifier settings for this project"
  </Accordion>

  <Accordion title="get_classifier">
    Get a single classifier with full configuration.

    **Parameters:**

    | Name            | Type   | Required | Description                              |
    | --------------- | ------ | -------- | ---------------------------------------- |
    | `classifier_id` | string | Yes      | The classifier ID                        |
    | `session_id`    | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Full classifier configuration object.

    **Example prompts:**

    * "Show me the details of this classifier"
    * "What model does this classifier use?"
  </Accordion>

  <Accordion title="list_classifier_models">
    List available classifier models with pricing information.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of available classifier model types with pricing.

    **Example prompts:**

    * "What classifier models are available?"
    * "Show me the pricing for classifier models"
  </Accordion>
</AccordionGroup>

## Portfolios (budget optimization)

Tools for inspecting portfolio configurations, performance history, and optimization scenarios.

<AccordionGroup>
  <Accordion title="list_portfolios">
    List all portfolios for a project with their id, name, goal, granularity, hidden status, metrics (`potentialMetric`, `actualMetric`, `actualSpend`), `targetsCount`, `isReady`, and `lastApplyTime`.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `project_id` | string | Yes      | The project ID                           |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of portfolio objects with configuration and summary metrics.

    **Example prompts:**

    * "What portfolios are configured in this project?"
    * "List all optimization portfolios"
    * "Which portfolios are ready for optimization?"
  </Accordion>

  <Accordion title="get_portfolio_history">
    Get portfolio performance history. When called with only `portfolio_id` (and optional `period`), returns a summary with per-period rows and plots. When `start_date` and `end_date` are provided, returns detailed period data including per-campaign breakdowns.

    **Parameters:**

    | Name           | Type   | Required | Description                                                                                                               |
    | -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
    | `portfolio_id` | string | Yes      | The portfolio ID                                                                                                          |
    | `period`       | string | No       | History period: `LAST_MONTH`, `LAST_THREE_MONTHS` (default), or `LAST_SIX_MONTHS`                                         |
    | `start_date`   | string | No       | Period start date (ISO-8601, e.g., `2025-01-01`). When provided with `end_date`, returns detailed per-campaign breakdowns |
    | `end_date`     | string | No       | Period end date (ISO-8601, e.g., `2025-01-31`). When provided with `start_date`, returns detailed per-campaign breakdowns |
    | `session_id`   | string | Yes      | Session ID returned by `analyze_request`                                                                                  |

    **Returns:** Performance history with per-period metrics and optional per-campaign detail.

    **Example prompts:**

    * "Show me the portfolio performance over the last 3 months"
    * "What was the campaign-level breakdown for January?"
    * "How has this portfolio performed over the last 6 months?"
  </Accordion>

  <Accordion title="get_portfolio_optimization">
    Get portfolio optimization data from the Optimize tab: current scenario, per-target optimization results with marginal metrics, diminishing return curves, and optional maturation/projection data.

    **Parameters:**

    | Name                       | Type   | Required | Description                                         |
    | -------------------------- | ------ | -------- | --------------------------------------------------- |
    | `portfolio_id`             | string | Yes      | The portfolio ID                                    |
    | `total_budget_limit`       | number | No       | Total budget constraint for the optimization period |
    | `total_daily_budget_limit` | number | No       | Daily budget constraint for optimization            |
    | `optimization_version`     | string | No       | Optimization algorithm version (default: `v7`)      |
    | `session_id`               | string | Yes      | Session ID returned by `analyze_request`            |

    **Returns:** Optimization scenario with per-target results, marginal metrics, and diminishing return curves.

    **Example prompts:**

    * "Show me the optimization recommendations for this portfolio"
    * "What would the optimal budget allocation look like with a \$50,000 monthly budget?"
    * "Show me the diminishing returns curves for portfolio targets"
  </Accordion>
</AccordionGroup>

## Experiments (geo tests)

Tools for inspecting geo-lift experiments.

<AccordionGroup>
  <Accordion title="list_experiments">
    List all experiments for a project with their status, preparation, and analysis results.

    **Parameters:**

    | Name         | Type   | Required | Description                              |
    | ------------ | ------ | -------- | ---------------------------------------- |
    | `project_id` | string | Yes      | The project ID                           |
    | `session_id` | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of experiment objects with status and results.

    **Example prompts:**

    * "What experiments are running?"
    * "Show me all geo tests and their status"
    * "List completed experiments with their results"
  </Accordion>

  <Accordion title="get_experiment">
    Get a single experiment with full details including plots, preparation, and analysis results.

    **Parameters:**

    | Name            | Type   | Required | Description                              |
    | --------------- | ------ | -------- | ---------------------------------------- |
    | `experiment_id` | string | Yes      | The experiment ID                        |
    | `session_id`    | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Full experiment object with plots, preparation data, and analysis results.

    **Example prompts:**

    * "Show me the results of this geo test"
    * "What was the measured lift in this experiment?"
    * "Show me the experiment preparation details"
  </Accordion>

  <Accordion title="list_experiment_custom_parameter_keys">
    Get available custom parameter keys for market-split experiments.

    **Parameters:**

    | Name            | Type   | Required | Description                              |
    | --------------- | ------ | -------- | ---------------------------------------- |
    | `conversion_id` | string | Yes      | The conversion ID                        |
    | `session_id`    | string | Yes      | Session ID returned by `analyze_request` |

    **Returns:** Array of custom parameter keys.

    **Example prompts:**

    * "What custom parameters can I use for geo test segmentation?"
    * "List available custom parameter keys for experiments"
  </Accordion>
</AccordionGroup>


# Optimization FAQ
Source: https://docs.segmentstream.com/optimization/faq

Common questions about the optimization module, including adoption calculation, prediction accuracy, and gain metrics.

<AccordionGroup>
  <Accordion title="What is the Optimization Overview page?">
    The Optimization Overview page shows how your portfolio has performed over time. It helps you understand the impact of your budget decisions and guides you in making data-driven adjustments to improve future results.
  </Accordion>

  <Accordion title="How is Adoption calculated?">
    Adoption measures how closely you follow the budget allocation recommendations:

    * **100% adoption** means you followed the recommendations exactly.
    * **0% adoption** means you kept the same budget distribution as before.
    * **Negative adoption** (down to -100%) means you made changes opposite to the recommendations.
    * The total budget amount does not affect adoption -- only the distribution matters.
  </Accordion>

  <Accordion title="How is Prediction Accuracy calculated?">
    Prediction Accuracy shows how well the system predicts future campaign performance:

    * **100% accuracy** means the predictions were perfect.
    * **0% accuracy** means the predictions were completely opposite to reality.
    * The calculation compares the system's predictions to the best and worst possible scenarios based on actual performance data.
  </Accordion>

  <Accordion title="Why might Prediction Accuracy be low?">
    Prediction Accuracy can be low due to:

    1. **Insufficient conversions** -- Very few conversions can make predictions unreliable.
    2. **Major external or internal changes** -- Competitor activities, seasonal changes, or other factors.
    3. **Approaching optimal state** -- When campaigns perform similarly, small changes can have large impacts.
  </Accordion>

  <Accordion title="Why is Adoption 100% when I increased the budget more than recommended?">
    Adoption measures how well you followed the recommended budget **distribution** across campaigns, not the total budget change. If you kept the same distribution but increased the overall budget, adoption can still be 100%.
  </Accordion>

  <Accordion title="How can actual gain increase when adoption is below 0%?">
    Actual gain can increase with negative adoption when:

    1. Prediction accuracy is low, and not following recommendations leads to better results.
    2. You take higher risks than recommended (for example, increasing a budget by 50% instead of the recommended 15%).
  </Accordion>

  <Accordion title="What is the difference between Gain/Loss, Potential Gain, and Missed Opportunity?">
    * **Gain/Loss** -- The actual impact of your budget changes compared to making no changes.
    * **Potential Gain** -- What could have been achieved if you fully followed the recommendations.
    * **Missed Opportunity** -- The difference between your potential gain and actual gain.
  </Accordion>
</AccordionGroup>


# Optimization overview
Source: https://docs.segmentstream.com/optimization/optimization-overview

Analyze your portfolio's performance over time with adoption rates, prediction accuracy, and gain metrics to make data-driven budget decisions.

The Optimization Overview page provides a view of your portfolio's performance over time. It helps you analyze the impact of your budget allocation decisions and make data-driven adjustments to maximize results in future periods.

## Key features

* Available immediately after portfolio creation.
* Serves as an audit tool to predict future outcomes.
* Allows you to decide whether to modify portfolio settings before starting optimization.

## Accessing the overview page

1. Navigate to the portfolio page.
2. Click the **Overview** button in the top right corner.

## Summary metrics

* **Total Gain** -- Net results achieved through budget allocation changes.
* **Missed Opportunity** -- Potential results lost due to not fully following recommendations.
* **Adoption Rate** -- Percentage indicating adherence to recommended budget distribution.
* **Prediction Accuracy** -- Accuracy of system recommendations based on previous data.

### Visual analysis

* **Cumulative Gain Chart** -- Displays cumulative gain and potential gain over the selected period.
* **Adoption Chart** -- Shows adoption rate and prediction accuracy over time.

<img alt="Optimization overview summary charts" />

### Detailed period analysis

For each period, the following metrics are provided:

* Spend
* Revenue or Conversions
* ROAS or CPA
* Gain/Loss
* Missed Opportunity
* Adoption
* Prediction Accuracy

<img alt="Period-by-period metrics table" />

### Portfolio breakdown

When you select a specific period, you see a detailed breakdown of each component:

* **Actual Spend** -- A chart showing two lines (recommended spend and actual spend). Hover over the chart to view daily values.
* **mROAS / mCPA** -- Marginal Return on Ad Spend or marginal Cost per Action, depending on the portfolio settings.
* **Recommended Changes** -- Suggested adjustments (budget and tROAS) to reach the recommended spend.
* **Recommended Spend** -- The suggested spend for the period, including the difference compared to the previous period.
* **Actual Spend** -- The actual spend for the period, including the difference compared to the previous period.
* **Daily Adherence** -- How closely the campaign settings in the ad platform align with the portfolio's recommended changes (currently only available for Google Ads).
* **Adoption** -- How closely the recommended budget spend allocations are being followed.

<img alt="Portfolio breakdown view for a selected period" />

## Understanding adoption

Adoption shows how closely your actual budget allocation follows the recommendations.

### The basics

Three budget distributions are compared:

1. **Previous** -- How you spent your budget in the last period.
2. **Recommended** -- How the system suggested you allocate your budget for this period.
3. **Actual** -- How you actually spent your budget in this period.

### How it works

Think of it as a scale between Previous and Recommended:

* If your actual allocation matches the **Recommended**, adoption = **100%**.
* If your actual allocation stays the same as **Previous**, adoption = **0%**.
* If your actual allocation falls between the two, adoption is somewhere between 0% and 100%.

For example: in the previous period you spent **100**, the recommendation was **150**, and you actually spent **125**. Since 125 is halfway between 100 and 150, the adoption score = **50%**.

## Understanding prediction accuracy

Prediction Accuracy measures how well the system predicts future campaign performance.

### The process

1. **Make predictions** -- The system predicts how each campaign will perform and recommends budget changes.
2. **Wait and observe** -- After the period ends, actual performance is evaluated.
3. **Calculate best and worst scenarios** -- Using actual performance data, the best possible outcome (perfect knowledge) and worst possible outcome are calculated.
4. **Measure the prediction** -- The initial prediction is placed between the best and worst scenarios.

### Interpretation

* If the prediction is close to the best scenario, Prediction Accuracy is close to **100%**.
* If the prediction is closer to the worst scenario, Prediction Accuracy is closer to **0%**.

## Understanding gain/loss, potential gain, and missed opportunity

### Gain/loss

Gain/loss measures the impact of your budget redistribution decisions compared to making no changes.

Two scenarios are compared:

* **Actual Result** -- Conversions or revenue achieved with your actual budget distribution.
* **No Action Result** -- Theoretical conversions or revenue if you had kept the previous period's distribution.

**Calculation:** Gain/Loss = Actual Result - No Action Result

* Positive value = gain due to your actions.
* Negative value = loss due to suboptimal actions.

### Potential gain

Potential gain shows what could have been achieved with full adoption of recommendations.

Two scenarios are compared:

* **Recommended Result** -- Theoretical conversions or revenue at 100% adoption.
* **No Action Result** -- Same as above.

**Calculation:** Potential Gain = Recommended Result - No Action Result

### Missed opportunity

Missed opportunity quantifies the gap between potential and actual performance.

**Calculation:** Missed Opportunity = Potential Gain - Actual Gain/Loss

A larger missed opportunity suggests room for improvement in your budget allocation strategy.

## Important considerations

1. **Calculation basis** -- Metrics such as Gain/Loss, Missed Opportunity, Adoption, and Prediction Accuracy are calculated only for campaigns or channels with consistent spending data in both the previous and current periods.
2. **Representation of campaign changes** -- Trendlines visualize why data may be incomplete for certain campaigns in the previous or current periods, reflecting decisions such as starting new campaigns or stopping existing ones.
3. **Incomplete data handling** -- Campaigns with incomplete data are still included in the detailed breakdown charts, allowing you to see the full picture of all campaign activity.
4. **Impact on metrics** -- All campaigns are included in standard metrics (total Spend, total Conversions), but campaigns with incomplete data do not participate in Adoption, Gain, and other optimization-specific metric calculations.


# Optimization
Source: https://docs.segmentstream.com/optimization/overview

Maximize ROI by intelligently reallocating your budget across all digital channels and campaigns with AI-powered recommendations.

The SegmentStream Optimization module helps you maximize ROI by intelligently reallocating your budget across all digital channels and campaigns.

## Getting started

Before using the optimization module:

* Set up [event tracking](/project-configuration/events-tracking).
* Connect at least one [data source](/project-configuration/data-sources/overview).
* Define at least one [conversion](/project-configuration/conversions).

## Navigation

To access the optimization module, navigate to the **Optimization** tab in the main menu. All your portfolios are listed on the main page along with their key metrics and potential uplift.

<img alt="Optimization module main page showing portfolio list" />

## Managing portfolios

To create a new portfolio, click **+ CREATE PORTFOLIO** at the top right of the main page. For details on creating and editing portfolios, read the [Portfolio setup](/optimization/portfolio-setup) guide.

To view budget allocation recommendations, select a portfolio from the main page. Refer to the [Portfolio optimize](/optimization/portfolio-optimize) guide to get the most from a portfolio.

## In this section

<CardGroup>
  <Card title="Portfolio setup" icon="sliders" href="/optimization/portfolio-setup">
    Configure portfolio settings including strategy, optimization goal, schedule, and granularity.
  </Card>

  <Card title="Portfolio optimize" icon="chart-mixed" href="/optimization/portfolio-optimize">
    View budget allocation recommendations and apply changes across your channel portfolio.
  </Card>

  <Card title="Optimization overview" icon="chart-line" href="/optimization/optimization-overview">
    Analyze portfolio performance over time with adoption, prediction accuracy, and gain metrics.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/optimization/faq">
    Common questions about optimization history, adoption, prediction accuracy, and gain calculations.
  </Card>
</CardGroup>


# Portfolio optimize
Source: https://docs.segmentstream.com/optimization/portfolio-optimize

View budget allocation recommendations, compare optimization scenarios, and apply budget changes across your channel portfolio.

The portfolio optimize page shows potential gains achievable through budget optimization recommendations, along with a list of all items included in the portfolio.

## Details bar

The bar displays the portfolio name and its settings. Click the **More Options** icon on the right to edit or delete the portfolio.

## Header

The header section provides an overview of the portfolio's actual performance during the selected time frame. Key metrics including Spend, Conversions, and CPA are displayed, along with the potential performance for the selected optimization schedule time frame under various budget scenarios.

## Scenario switcher

Click on any scenario to recalculate the budget allocation recommendations and visualize the potential performance.

### Default optimization scenarios

1. **Scenario 1 -- Fixed spend:** Optimize campaigns by redistributing a budget equivalent to the one used in the selected time frame.
2. **Scenario 2 -- Spend +15%:** Recommend a budget adjustment to achieve more conversions by increasing the budget by 15%.
3. **Scenario 3 -- Spend +30%:** Recommend a budget adjustment to achieve more conversions by increasing the budget by 30%.

### Custom scenarios

If the default scenarios do not fit your budget or business needs, create custom scenarios with your preferred budget by clicking **+ ADD CUSTOM SCENARIO**.

<Warning>
  Making large changes to your spending -- more than 15% different from your current spend -- could significantly change how your portfolio performs.
</Warning>

Click the **More Options** icon on the top right corner of each custom scenario for further adjustments.

## Item list

A list of the campaigns, ad platforms, channels, or custom dimension groups within the portfolio with the following columns:

* **Daily Spend** -- Daily ad spend for the set reporting period.
* **New Daily Spend** -- The recommended budget adjustment and proposed spend for the selected time frame.
* **Revenue/Conversions** -- Total revenue or conversions for the selected time frame, depending on the selected strategy.
* **Predicted ROAS/CPA** -- Predicted return on ad spend or cost per action for the selected time frame.
* **Predicted mROAS/mCPA** -- Predicted marginal return on ad spend or cost per action for the selected time frame.
* **More** -- Allows you to delete the item from the portfolio for more targeted optimization of other items.

<img alt="Portfolio optimize item list with budget recommendations" />

## Apply functionality

SegmentStream allows you to apply the recommended budget changes across your channel portfolio with a single click.

<Steps>
  <Step title="Select a scenario">
    Choose the optimization scenario you want to use.
  </Step>

  <Step title="Review changes">
    Click the **Review changes** button.

    <img alt="Review changes button" />
  </Step>

  <Step title="Confirm changes">
    Review and confirm the changes, then click **CONFIRM**.
  </Step>

  <Step title="Changes applied">
    A message confirms that budget changes have been applied.
  </Step>
</Steps>

Once changes are applied, the **Review changes** button is disabled until the end of the optimization period, unless a different optimization strategy is selected.

<img alt="Review changes button disabled after applying" />


# Portfolio setup
Source: https://docs.segmentstream.com/optimization/portfolio-setup

Configure optimization portfolios with strategy, goal, schedule, and granularity settings to receive budget allocation recommendations.

A portfolio is a report that provides recommendations for optimizing the budget of a specific set of campaigns, ad platforms, or channels to achieve a defined goal.

The algorithm assesses the portfolio's potential and suggests optimal budget reallocation strategies for the selected time frame, along with estimates of potential gains and ROI uplift.

## Portfolio settings

To set up a portfolio, configure the following settings. All options except the strategy and optimization granularity can be edited later.

<img alt="Portfolio settings configuration form" />

### Strategy

The portfolio strategy defines the goal you want to achieve. For each portfolio, choose the optimization strategy that best aligns with your goals:

* **Maximize Conversions** -- Allocate budget to generate the highest number of conversions.
* **Maximize Revenue** -- Allocate budget to generate the highest revenue.

### Optimization goal

Select the conversion and attribution model for your optimization goal.

For more information on attribution models, refer to the [Attribution models](/project-configuration/attribution-models) guide.

### Optimization schedule

Choose the time interval to receive budget recommendations -- weekly, bi-weekly, or monthly. Your portfolio's actual performance during the selected time interval is compared to its potential future performance within the chosen time frame.

### Optimization granularity

This setting controls the level at which budget allocation recommendations are generated.

#### Campaign level

SegmentStream provides recommendations specific to individual campaigns. This option is ideal if you prefer a detailed, micromanaged approach to budget allocation with precise control over campaign-level spending.

#### Ad platform level

SegmentStream suggests an overall budget allocation strategy for optimal performance across each ad platform. Choose this option if you prefer managing marketing budgets at a broader level.

#### Channel and custom granularity

You can use the predefined Channel dimension or create custom dimensions to group campaigns and ad platforms based on your business logic. This tailors the optimization recommendations to align with your specific needs. For instructions on creating custom dimensions, refer to the [Custom dimensions](/attribution/custom-dimensions) guide.

### Campaign, ad platform, channel, and custom dimension selection

You can choose to optimize only specific groups. For instance, you can exclude groups that do not scale effectively.


# Overview
Source: https://docs.segmentstream.com/overview

SegmentStream lets you measure advertising ROI and other KPIs by consolidating first-party and third-party data with ML-powered attribution.

## What is SegmentStream?

SegmentStream lets you measure your advertising ROI and other KPIs by consolidating first-party and third-party data. With the power of Machine Learning, it evaluates the incremental value of each marketing touchpoint across various devices and browsers.

For an in-depth understanding of how SegmentStream supports multi-touch attribution, refer to the [SegmentStream basics](/segmentstream-basics) article.

## How to integrate SegmentStream

The integration process with SegmentStream is straightforward. Follow the key steps below or jump straight to the [Quick start](/quick-start) guide.

<Steps>
  <Step title="Create an account">
    Sign up using the link provided by your SegmentStream manager.
  </Step>

  <Step title="Configure your data warehouse">
    Connect a data warehouse to store and process your project's data (optional).
  </Step>

  <Step title="Set up event tracking">
    Configure event tracking on your website using GTM or GTAG.js.
  </Step>

  <Step title="Connect marketing platforms">
    Connect your advertising platforms with built-in integrations.
  </Step>

  <Step title="Define conversions">
    Set up your business conversions to track.
  </Step>

  <Step title="Optimize budget allocation">
    Use the AI-powered budget allocation recommendation engine.
  </Step>

  <Step title="Analyze KPIs">
    Review your KPIs through built-in reports.
  </Step>
</Steps>

## How to use SegmentStream

SegmentStream offers a range of modules designed to enhance your data analysis and marketing strategies.

<CardGroup>
  <Card title="Project configuration" icon="gear" href="/project-configuration/overview">
    Set up your data warehouse, event tracking, advertising platform integrations, and conversions.
  </Card>

  <Card title="Dashboards" icon="chart-line" href="/dashboards">
    Monitor and analyze key insights at a glance with an intuitive dashboard overview.
  </Card>

  <Card title="Attribution" icon="diagram-project" href="/attribution/overview">
    Customize reports and gain insights into marketing analytics with configurable attribution models.
  </Card>

  <Card title="Optimization" icon="wand-magic-sparkles" href="/optimization/overview">
    Maximize ROI through AI-powered budget reallocation across all your digital channels and campaigns.
  </Card>

  <Card title="Geo Tests" icon="earth-americas" href="/geo-tests">
    Measure the real sales impact of your paid media investments with controlled geo experiments.
  </Card>

  <Card title="MCP" icon="plug" href="/mcp/overview">
    Connect AI tools to your SegmentStream workspace to query attribution data through natural language.
  </Card>
</CardGroup>

## Troubleshooting and FAQs

Each section in the documentation includes an FAQ page addressing common questions and potential issues:

* [Attribution FAQ](/attribution/faq)
* [Data sources FAQ](/project-configuration/data-sources/faq)
* [Optimization FAQ](/optimization/faq)

## Support and feedback

If you encounter any issues, use the support button within your dashboard to communicate directly with the product team.


# Attribution models
Source: https://docs.segmentstream.com/project-configuration/attribution-models

Configure attribution models in SegmentStream to determine how marketing touchpoints receive credit for conversions.

Marketing attribution is the process of determining which marketing efforts contribute to conversions.

All attribution models in SegmentStream are non-direct. This means that if there was a direct visit to the website in a sequence of touchpoints, SegmentStream will not give any credit to this visit. The only way for conversion credit to be attributed to the direct channel is when there were one or more direct visits that ended up with a conversion.

For more information on how attribution models work, refer to the [SegmentStream basics](/segmentstream-basics) article.

## Managing attribution models

To manage your attribution models, navigate to **Settings** > **Attribution Models**.

* To create a new attribution model, click **+ ADD** in the top-right corner. This opens the configuration window.
* To edit an existing attribution model, click on its name in the list.

<img alt="Attribution models list" />

## Model types

SegmentStream provides four types of attribution models, each of which can be customized to meet your specific requirements.

<CardGroup>
  <Card title="Last-click" icon="arrow-right-to-bracket" href="/project-configuration/attribution-models/last-click">
    Assigns all credit to the final marketing touchpoint before conversion.
  </Card>

  <Card title="First click" icon="arrow-right-from-bracket" href="/project-configuration/attribution-models/first-click">
    Assigns all credit to the initial marketing touchpoint before conversion.
  </Card>

  <Card title="Multi-touch" icon="diagram-project" href="/project-configuration/attribution-models/multi-touch">
    Evaluates each session for lift in purchase probability and assigns credit based on intent signals.
  </Card>

  <Card title="Visit Scoring" icon="chart-line" href="/project-configuration/attribution-models/visit-scoring">
    Assigns fractional conversion credit based on user behaviour after each click.
  </Card>
</CardGroup>

<Tabs>
  <Tab title="Last-click">
    The last-click attribution model assigns all credit for a conversion to the final marketing touchpoint that a customer interacts with before converting.

    ### Configuration

    * **Name** -- enter the name as you want it to appear in the reports dashboard.
    * **Attribution type** -- select `Last-click` from the selector.
    * **Attribution window** -- determines the time window within which a conversion can be attributed to the last significant click. For example, if a user visits a website through Facebook Ads and, within 14 days, visits the website directly and makes a conversion, the attribution window affects which touchpoint gets credit in reports.

    ### Significant traffic sources

    You can adjust your attribution model by excluding unwanted referrers. For instance, if you wish to provide credit only to paid channels like Facebook, set up the following filter:

    * Dimension: `Ad Platform`
    * Operator: `is not equal to`
    * Value: `(not set)`

    In this case, SegmentStream attributes all the value to the last paid click, ignoring not only direct visits but also organic, email, referral, and other channels.

    <img alt="Last-click attribution model configuration" />
  </Tab>

  <Tab title="First click">
    The first click attribution model assigns all credit for a conversion to the initial marketing touchpoint that a customer interacts with before converting.

    ### Configuration

    * **Name** -- enter the name as you want it to appear in the reports dashboard.
    * **Attribution type** -- select `First Click` from the selector.
  </Tab>

  <Tab title="Multi-Touch">
    The multi-touch attribution model evaluates each session for lift in purchase probability and assigns credit only if:

    * The visit increased the likelihood of conversion.
    * Behavioural signals (for example, product views, time on site, repeat visits) show meaningful intent.

    ### Configuration

    * **Name** -- enter the name as you want it to appear in the reports dashboard.
    * **Attribution type** -- select `Multi-Touch` from the selector.

    ### Significant traffic sources

    You can adjust your attribution model by excluding unwanted referrers. For instance, if you wish to provide credit only to paid channels and to non-brand campaigns, set up the following filters:

    * Dimension: `Ad Platform`, Operator: `is not empty`
    * Dimension: `Campaign`, Operator: `does not contain`, Value: `brand`

    In this case, SegmentStream attributes value to paid non-brand sessions, unless such sessions were not tracked.
  </Tab>

  <Tab title="Visit Scoring">
    The Visit Scoring attribution model is a multi-touch, cross-channel, cross-device attribution model that assigns fractional parts of conversion and conversion value based on user behaviour after each click.

    For more information, read the [SegmentStream basics](/segmentstream-basics) article.

    ### Configuration

    * **Name** -- enter the name as you want it to appear in the reports dashboard.
    * **Attribution type** -- select `Visit Scoring` from the selector.

    ### Significant traffic sources

    You can adjust your attribution model by excluding unwanted referrers. For instance, if you wish to provide credit only to paid channels, set up the following filter:

    * Dimension: `Ad Platform`
    * Operator: `is not empty`

    In this case, SegmentStream attributes all the value to paid clicks, ignoring direct visits, organic, email, referral, and other channels.

    <img alt="Visit Scoring attribution model configuration" />
  </Tab>
</Tabs>


# First click
Source: https://docs.segmentstream.com/project-configuration/attribution-models/first-click

Configure the first click attribution model in SegmentStream to assign conversion credit to the initial marketing touchpoint.

The first click attribution model assigns all credit for a conversion to the initial marketing touchpoint that a customer interacts with before converting.

## Name

You can name the attribution model as you want to see it displayed in the reports dashboard.

## Attribution type

Select the `First Click` option from the selector.


# Last-click
Source: https://docs.segmentstream.com/project-configuration/attribution-models/last-click

Configure the last-click attribution model in SegmentStream to assign conversion credit to the final marketing touchpoint.

The last-click attribution model assigns all credit for a conversion to the final marketing touchpoint that a customer interacts with before converting.

For more information on attribution models, read the [SegmentStream basics](/segmentstream-basics) article.

## Name

You can name the attribution model as you want to see it displayed in the reports dashboard.

## Attribution type

Select the `Last-click` option from the selector.

## Attribution window

The attribution window determines the time window within which a conversion can be attributed to the last significant click. For example, if a user visits a website through Facebook Ads and, within 14 days, visits the website directly and makes a conversion, the attribution window affects the results seen in the reports.

## Significant traffic sources

You can adjust your attribution model by excluding unwanted referrers.

For instance, if you wish to provide credit only to paid channels like Facebook, you can set up the following filter:

* Dimension: `Ad Platform`
* Operator: `is not equal to`
* Value: `(not set)`

In this case, SegmentStream attributes all the value to the last paid click, ignoring not only direct visits, but also organic, email, referral, and other channels.

Referring back to the example above, in the reports, the entire conversion is attributed to Facebook ads, because attribution models ignore Google Organic and Direct channels.

<img alt="Last-click attribution model configuration" />


# Multi-touch
Source: https://docs.segmentstream.com/project-configuration/attribution-models/multi-touch

Configure the multi-touch attribution model in SegmentStream to assign conversion credit based on session lift in purchase probability.

The multi-touch attribution model evaluates each session for lift in purchase probability and assigns credit only if:

* The visit increased the likelihood of conversion.
* Behavioural signals (e.g. product views, time on site, repeat visits) show meaningful intent.

## Name

You can name the attribution model as you want to see it displayed in the reports dashboard.

## Attribution type

Select the `Multi-Touch` option from the selector.

## Significant traffic sources

You can adjust your attribution model by excluding unwanted referrers.

For instance, if you wish to provide credit only to paid channels and to non-brand campaigns, you can set up the following filters:

* Dimension: `Ad Platform`, Operator: `is not empty`
* Dimension: `Campaign`, Operator: `does not contain`, Value: `brand`

In this case, SegmentStream attributes value to paid non-brand sessions, unless such sessions were not tracked.


# Visit Scoring
Source: https://docs.segmentstream.com/project-configuration/attribution-models/visit-scoring

Configure the Visit Scoring attribution model in SegmentStream to assign fractional conversion credit based on user behaviour.

The Visit Scoring attribution model is a multi-touch, cross-channel, cross-device attribution model that assigns fractional parts of conversion and conversion value based on user behaviour after each click.

For more information, read the [SegmentStream basics](/segmentstream-basics) article.

## Name

You can name the attribution model as you want to see it displayed in the reports dashboard.

## Attribution type

Select the `Visit Scoring` option from the selector.

## Significant traffic sources

You can adjust your attribution model by excluding unwanted referrers.

For instance, if you wish to provide credit only to paid channels, you can set up the following filter:

* Dimension: `Ad Platform`
* Operator: `is not empty`

In this case, SegmentStream attributes all the value to paid clicks, ignoring not only direct visits, but also organic, email, referral, and other channels.

<img alt="Visit Scoring attribution model configuration" />


# Conversions
Source: https://docs.segmentstream.com/project-configuration/conversions

Set up and manage conversions to measure the performance of your marketing activity in SegmentStream.

Conversions allow you to measure the performance of marketing activity. To create a conversion, click **+ ADD** at the top right corner. This opens a window where you can select which type of conversion you want to create.

SegmentStream supports the following conversion types:

| Type                                      | Description                                                              | Availability |
| ----------------------------------------- | ------------------------------------------------------------------------ | ------------ |
| [Simple](#simple-conversion)              | Track purchase or custom events collected through your tracker           | All plans    |
| [Combined](#combined-conversion)          | Merge two or more simple conversions into one                            | All plans    |
| [Custom](#custom-conversion)              | Write SQL against raw BigQuery data for offline or CRM-based conversions | Enterprise   |
| [Lead Scoring](#lead-scoring-conversion)  | ML-powered lead qualification and value prediction                       | Enterprise   |
| [Conversions export](#conversions-export) | Export conversion signals to ad platforms                                | Enterprise   |

<CardGroup>
  <Card title="Simple conversions" icon="bullseye" href="/project-configuration/conversions/simple-conversions">
    Track purchase or custom events collected through the SegmentStream tracker.
  </Card>

  <Card title="Combined conversions" icon="layer-group" href="/project-configuration/conversions/combined-conversions">
    Merge two or more simple conversions into a single conversion.
  </Card>

  <Card title="Custom conversions" icon="code" href="/project-configuration/conversions/custom-conversions">
    Write SQL against raw BigQuery data for offline or CRM-based conversions.
  </Card>

  <Card title="Lead Scoring" icon="brain" href="/project-configuration/conversions/lead-scoring-conversions">
    ML-powered lead qualification and value prediction.
  </Card>

  <Card title="Conversions export" icon="share-from-square" href="/project-configuration/conversions/conversions-export">
    Export conversion signals to advertising platforms.
  </Card>
</CardGroup>

## Simple conversion

Every event you collect through the SegmentStream tracker can be marked as a conversion. To create a simple conversion, navigate to the **Conversions** page, click **+ ADD**, and select **Simple conversion**.

There are two types of simple conversions: **Purchase** and **Custom event**.

### Purchase

The standard conversion for e-commerce websites. To create this type of conversion, name the conversion (for example, "Purchase"), make sure the Purchase conversion event type is selected, and click **SAVE**.

#### Filters

To configure a filter, select from a list of built-in default dimensions, custom dimensions and metrics based on the event parameters collected to your GA4 property, as well as product dimensions.

For example, if you want to track purchases with a total value over \$100, use the **Event Transaction Total** dimension as displayed in the screenshot below.

<img alt="Purchase conversion filter configuration" />

#### Conversions deduplication

By default, **Purchase** conversions are deduplicated by order ID. To track only the first purchase per user, enable the **Deduplicate conversions by User** option.

#### Conversions adjustment

Enabling conversions adjustment allows you to specify a time window, in days, during which conversion data in SegmentStream can be updated based on refunds processed in GA4. This keeps SegmentStream data aligned with your GA4 reports.

#### Normalize by conversion

Adjusts the value of the selected conversion relative to another conversion type (for example, **Purchase**). This helps in benchmarking, scaling, and aligning conversion values to better reflect business impact and optimize attribution.

<img alt="Normalize by conversion setting" />

### Custom event

All events other than the purchase event can be used as conversions through this type. To create this type of conversion, name the conversion (for example, "Lead"), select the Custom conversion event type, and then configure the following sections.

#### Filters

To configure a filter, select from a list of built-in default dimensions, custom dimensions and metrics based on the event parameters collected to your GA4 property, as well as product dimensions.

As an example, the **Event Action** dimension values contain the names of the events as they are sent to your GA4 property, so creating a conversion for the event with the **lead** event name would require the setup illustrated in the screenshot below.

#### Conversion value

If your conversion has a monetary value that you would like to see in SegmentStream reports, you have two options:

* **Event value** -- useful when the value of each conversion might differ. This requires the `value` event parameter to be configured in the event sent to GA4.
* **Manual value** -- all conversions have an equal value.

If you do not have a monetary value for the conversion, select **No value**.

#### Conversions deduplication

Enabling **Deduplicate conversions by User** filters out conversions that happened by users with the same Google Client ID or User ID within a set day window.

#### Normalize by conversion

Adjusts the value of the selected conversion relative to another conversion type (for example, **Purchase**). This helps in benchmarking, scaling, and aligning conversion values to better reflect business impact and optimize attribution.

<img alt="Custom event conversion setup" />

## Combined conversion

If you have two or more conversions, you can combine them into a single conversion. Every time one of your simple conversions is triggered, your combined conversion is triggered as well.

To create a combined conversion, navigate to the **Conversions** page, click **+ ADD**, and select **Combined conversion**.

### Conversions deduplication

Enabling deduplication filters out conversions that happened by users with the same Google Client ID within a set day window.

<img alt="Combined conversion setup" />

## Custom conversion

<Note>
  Custom conversions are available only on the [enterprise plan](https://segmentstream.com/pricing).
</Note>

Custom conversions enable you to create conversions by writing an SQL query that uses any raw data present in your Google BigQuery. A common use case is tracking offline conversions through CRM systems.

Benefits of using custom conversions:

1. They are created and maintained by the SegmentStream technical team.
2. Any data in your BigQuery can be used to calculate conversions.

### Using CRM data

SegmentStream supports data sources for the following CRM tools, allowing you to load data directly into the connected Google BigQuery dataset:

* HubSpot
* Salesforce
* Microsoft Dynamics
* Pipedrive

If you use a different CRM tool, you will need to manually export the CRM data to BigQuery. Alternatively, reach out to your SegmentStream manager for assistance.

### Creating a custom conversion

The SQL query results should consist of three columns: `id`, `client_id`, and `created`. Additional columns are optional based on available data.

* The `created` column must always contain a valid timestamp.
* For optional columns, assign `NULL` only if data is occasionally unavailable. If all values for a column are unknown, omit that column from the query.
* If your query involves a partitioned table (for example, partitioned by `date`), include a filter on the partition column in the `WHERE` clause:
  ```sql theme={null}
  WHERE date BETWEEN @start_date AND @end_date
  ```

| SQL field name | Type                                      | Description                                                                                                                             | Required |
| -------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `id`           | STRING                                    | ID of conversion/order used for deduplication                                                                                           | Yes      |
| `client_id`    | STRING                                    | Google Analytics client ID. If not provided, the conversion will be marked as (not attributed) in reports.                              | Yes      |
| `created`      | TIMESTAMP                                 | Date and time of the conversion                                                                                                         | Yes      |
| `value`        | FLOAT64                                   | The monetary value of the conversion                                                                                                    | No       |
| `currency`     | STRING                                    | 3-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code (USD, EUR, GBP). If NULL, project currency is used. | No       |
| `is_qualified` | BOOLEAN                                   | True if conversion reached target status                                                                                                | No       |
| `params`       | ARRAY\<STRUCT\<key STRING, value STRING>> | Array of custom parameters passed with each conversion                                                                                  | No       |
| `user_id`      | STRING                                    | User's ID from the CRM                                                                                                                  | No       |

<Tip>
  For lead generation businesses, collecting the conversion value is recommended as it allows SegmentStream to enhance its ML model.
</Tip>

#### Collecting geo data from CRM

To improve your market selection options for launching geo tests, consider collecting geo location data in your CRM.

When adding geo data from your CRM, include it in the `params` column as key-value pairs. The `key` should indicate the geographical scope (city, country, or region), while the `value` should specify the name of the geo location.

#### Example

After a user purchases a service on your website, they need to confirm their order when contacted by your call centre staff. Once a call centre operator receives confirmation, they update the status in the CRM system.

To view users who have confirmed their purchase in SegmentStream reports, load the data from the CRM system into BigQuery. Then create a custom conversion with SQL that extracts conversions from the CRM data, along with a client identifier used to stitch the conversion to the user's website session.

The following code runs a daily check on website orders created within the last 30 days. It marks them as conversions if their CRM statuses are "confirmed" or "paid", and collects the country, region, and city information.

```sql theme={null}
SELECT
  id,
  userId AS client_id,
  createdAt AS created,
  orderValue AS value,
  'GBP' AS currency,
  IF(orderStatus IN ('confirmed', 'paid'), TRUE, FALSE) AS is_qualified,
  ARRAY(SELECT AS STRUCT * FROM UNNEST(properties) WHERE key IN ('country', 'region', 'city')) AS params
FROM
  `bq-project-id.dataset_id.CRM_order_table_5806956`
WHERE
  date BETWEEN DATE_SUB(@start_date, INTERVAL 30 DAY) AND @end_date
```

<img alt="Custom conversion SQL configuration" />

### Predicted value

You can use a predicted value for your custom conversions. This value is calculated by linking a target conversion's value to the probability of that conversion occurring.

To activate this feature, the `user_id` fields in both the target custom conversion and in any custom conversion for which you want a predicted value should be based on the same identifier. Also, the CRM data that the custom conversion is built on should contain user-related data -- such as geolocation, activities, and any other information particular to that user. This data serves as features for the machine learning model that predicts the value.

When you validate the SQL for your custom conversion, you will find an option called "Predicted value." Choosing this reveals two more fields:

* **Target conversion** -- shows all eligible conversions for value prediction. To qualify, a custom conversion needs the `user_id` field and at least one conversion in the past 60 days.
* **Conversion window** -- sets the maximum timeframe for linking conversions.

Once you save your settings, the ML model calculates the predicted value for each conversion within about 15 minutes.

#### Use case

Consider this scenario: you track two types of conversions. The first is called "Lead," which occurs when someone submits a form. The second, "Deal Closed," happens when a lead converts into a deal. Each deal has a unique value.

To estimate the value of each lead, create a modified "Lead" conversion. Enhance the SQL by incorporating CRM data features such as the number of times the user has contacted sales, their business country, and their job title. Set the conversion value to "Predicted value," choose "Deal Closed" as the target conversion, and set the conversion window to 40 days to accommodate the typical duration within which most leads convert into deals.

After SegmentStream completes its calculations, you can view the predicted value of each lead based on the value of the deals that have closed.

<img alt="Predicted value configuration" />

### Conversions adjustment

Enabling conversions adjustment allows you to specify a time window, in days, during which conversion data in SegmentStream can be updated based on changes detected in your CRM. This keeps SegmentStream data aligned with your CRM records.

<img alt="Conversions adjustment settings" />

### BigQuery access issues

If the data from your CRM is exported to a different project than the one specified in the SegmentStream BigQuery settings, provide the SegmentStream service account email with the **BigQuery Data Viewer** and **BigQuery User** roles for that project before setting up custom conversions.

## Lead Scoring conversion

<Note>
  Lead Scoring is an enterprise feature that requires collaboration with the SegmentStream data team for implementation and optimization.
</Note>

Lead Scoring is an advanced conversion type that uses machine learning to assign quality scores to your leads based on their characteristics and likelihood to convert. This helps you identify high-value prospects and optimize your marketing spend toward leads that are most likely to generate revenue.

Lead Scoring analyzes your lead data to identify qualified leads and estimates their potential deal value. This allows you to:

* Focus on qualified leads that are most likely to convert
* Optimize marketing campaigns toward lead quality, not quantity
* Improve ROI by focusing budget on channels that generate valuable leads
* Export qualified leads to advertising platforms for better targeting

### Getting started

<Steps>
  <Step title="Assess your data">
    Review whether you have the required lead and sales data.
  </Step>

  <Step title="Choose integration method">
    Determine if you can use a standard CRM integration or need custom data setup.
  </Step>

  <Step title="Contact SegmentStream">
    Reach out to discuss your specific requirements and begin the setup process.
  </Step>
</Steps>

### Data requirements

There are two approaches depending on your CRM setup:

<Tabs>
  <Tab title="Standard CRM integration">
    If you use a well-known CRM system, SegmentStream can automatically connect to your existing data. For example, [HubSpot](/project-configuration/data-sources/hubspot) has a ready-to-use integration.

    Contact your SegmentStream manager to get details about connecting your specific CRM system. With standard CRM integration, SegmentStream automatically collects lead data and deal outcomes to train the scoring model.
  </Tab>

  <Tab title="Custom data integration">
    If you use a custom CRM or one not in the SegmentStream catalog, provide lead and sales data in the following format.

    **Leads data table**

    Required fields:

    | Field              | Description                                          |
    | ------------------ | ---------------------------------------------------- |
    | `created_at`       | When the lead was created                            |
    | `updated_at`       | When the lead was last updated                       |
    | `lead_id`          | Unique identifier for each lead                      |
    | `google_client_id` | Google Analytics Client ID when the lead was created |
    | `user_id`          | Internal user identifier that links to sales data    |

    Include as many relevant lead characteristics as possible to improve model accuracy: email, name, company name, company size, industry, job title, seniority level, lead source, country, annual revenue, budget, pain points, and product interest.

    **Sales/deals data table**

    Required fields:

    | Field        | Description                                 |
    | ------------ | ------------------------------------------- |
    | `created_at` | When the deal was closed                    |
    | `updated_at` | When the deal was last updated              |
    | `order_id`   | Unique identifier for each sale/deal        |
    | `value`      | Revenue amount of the deal                  |
    | `user_id`    | Links back to the lead data (same user\_id) |

    <Warning>
      To accurately predict customer lifetime value, include ALL purchases attributed to each `user_id` in the sales table, not only the first purchase. This helps the model understand the complete revenue potential of similar leads.
    </Warning>
  </Tab>
</Tabs>

### How Lead Scoring works

1. **Data analysis** -- SegmentStream analyzes your historical lead and sales data to identify patterns.
2. **Model training** -- Machine learning models learn which lead characteristics predict successful conversions.
3. **Qualification** -- New leads are evaluated and only those meeting quality thresholds become conversions.
4. **Value prediction** -- The system estimates potential deal value for each qualified lead.
5. **Daily updates** -- Lead qualification and scoring are updated daily as new data becomes available.

### What you get

* **Qualified lead conversions** -- only high-quality leads that meet configurable thresholds are created as conversions in SegmentStream.
* **Predicted deal values** -- estimated revenue potential for each qualified lead.
* **Exportable data** -- qualified lead conversions can be exported to ad platforms such as Google Ads and Meta for enhanced conversions, lookalike audiences, and bid optimization.
* **Reporting and analytics** -- use Lead Scoring conversions in SegmentStream reports to analyze qualified lead performance by traffic source and compare channel effectiveness.

### Best practices

* **Capture Google Client ID** -- ensure your forms capture the Google Analytics Client ID to link website behavior with lead data.
* **Collect rich attributes** -- the more relevant information you collect about leads at the time of creation, the more accurate the scoring will be.
* **Maintain data quality** -- keep lead and sales data clean and up-to-date.
* **Historical data** -- provide at least 6 months of historical data for optimal model training.

<Note>
  Attributes must be available immediately when the lead is created to ensure they can be used for next-day conversion processing. Attributes added later in your sales process may not be available for new lead scoring.
</Note>

## Conversions export

<Note>
  Conversions export is available only on the [enterprise plan](https://segmentstream.com/pricing).
</Note>

SegmentStream enables you to export conversion signals to advertising and analytics platforms. You can leverage conversion modelling by using the export feature to provide ad platforms with more value signals. Additionally, you can send conversion signals from offline data by creating [custom conversions](#custom-conversion) and exporting them.

<Steps>
  <Step title="Choose the conversion">
    Select the conversion you wish to export.
  </Step>

  <Step title="Open exports section">
    Scroll down to the Exports section.
  </Step>

  <Step title="Add export">
    Click **+ ADD EXPORT**.
  </Step>

  <Step title="Select platform">
    Select the desired ad platform for your export.
  </Step>

  <Step title="Configure and save">
    Configure the export settings and save. Each morning, data from the previous day will be exported to the ad platform.
  </Step>
</Steps>

<img alt="Conversions export configuration" />

## FAQ

For answers to common questions about conversions, see the [Conversions FAQ](/project-configuration/conversions-faq).


# Combined conversions
Source: https://docs.segmentstream.com/project-configuration/conversions/combined-conversions

Merge two or more simple conversions into a single conversion in SegmentStream.

If you have two or more conversions, you can combine them into a single conversion. Every time one of your simple conversions is triggered, your combined conversion is triggered as well.

To create a combined conversion, navigate to the **Conversions** page, click **+ ADD**, and select **Combined conversion**.

## Conversions deduplication

Enabling deduplication filters out conversions that happened by users with the same Google Client ID within a set day window.

<img alt="Combined conversion setup" />


# Conversions export
Source: https://docs.segmentstream.com/project-configuration/conversions/conversions-export

Export conversion signals from SegmentStream to advertising and analytics platforms.

<Note>
  Conversions export is available only on the [enterprise plan](https://segmentstream.com/pricing).
</Note>

SegmentStream enables you to export conversion signals to advertising and analytics platforms. You can leverage conversion modelling by using the export feature to provide ad platforms with more value signals. Additionally, you can send conversion signals from offline data by creating [custom conversions](/project-configuration/conversions/custom-conversions) and exporting them.

## Setting up a conversion export

<Steps>
  <Step title="Choose the conversion">
    Select the conversion you wish to export.
  </Step>

  <Step title="Open exports section">
    Scroll down to the Exports section.
  </Step>

  <Step title="Add export">
    Click **+ ADD EXPORT**.
  </Step>

  <Step title="Select platform">
    Select the desired ad platform for your export.
  </Step>

  <Step title="Configure and save">
    Configure the export settings and save. Each morning, data from the previous day will be exported to the ad platform.
  </Step>
</Steps>

<img alt="Conversions export configuration" />

## Supported platforms

<CardGroup>
  <Card title="Facebook" icon="facebook" href="/project-configuration/conversions/conversions-export/facebook-conversions-export">
    Export conversions to your Facebook pixel for improved ad targeting.
  </Card>

  <Card title="Google Ads" icon="google" href="/project-configuration/conversions/conversions-export/google-ads-conversions-export">
    Export conversions to Google Ads for bidding optimization.
  </Card>

  <Card title="LinkedIn" icon="linkedin" href="/project-configuration/conversions/conversions-export/linkedin-conversions-export">
    Export conversions to your LinkedIn ad account.
  </Card>

  <Card title="Google Analytics 4" icon="chart-simple" href="/project-configuration/conversions/conversions-export/google-analytics-4-conversions-export">
    Export conversions to your GA4 property.
  </Card>
</CardGroup>


# Facebook conversions export
Source: https://docs.segmentstream.com/project-configuration/conversions/conversions-export/facebook-conversions-export

Export SegmentStream conversions to your Facebook pixel for improved ad targeting and measurement.

<Steps>
  <Step title="Select a conversion">
    Inside the admin panel, go to the **Conversions** page and select the conversion you want to export as an event to your Facebook pixel.
  </Step>

  <Step title="Add export">
    In the conversion menu, click **Add Export**.

    <img alt="Add export button" />
  </Step>

  <Step title="Authenticate with Facebook">
    Select **Facebook** in the window that opens and go through the authentication flow.
  </Step>

  <Step title="Configure export settings">
    After the authentication flow, you should see the Facebook export settings.

    * Enter your **Pixel ID** (which can be found inside the [Facebook Events Manager](https://www.facebook.com/events_manager2/)).
    * Fill in the **Event name** for each conversion. We recommend keeping the event name the same as your conversion name within SegmentStream.
    * Choose whether to enable **Enhanced Tracking**, which exports additional user data such as email, name, and other details if available in the conversion data.
    * Choose whether to enable **Retrospective Updates**, which allows exporting conversions retroactively within the set lookback window. This is useful when conversions are exported from your CRM, particularly when conversions are validated several days after they occur.
  </Step>

  <Step title="Save">
    Click **Save**. Conversions will be automatically exported to Facebook daily after data processing for the previous day is completed.
  </Step>
</Steps>

<Info>
  It might take up to 1 hour before you see the first batch of events from SegmentStream.
</Info>

## Cookies custom fields setup

By default, Google Analytics 4 does not collect data about first-party cookies like `_fbp`. This cookie is required to send additional data through server-side conversion tracking.

<Tabs>
  <Tab title="Using GTM">
    <Steps>
      <Step title="Create a cookie variable">
        Inside your Google Tag Manager, go to **Variables**, click **New**, and choose the **1st Party Cookie** variable type from the list.
      </Step>

      <Step title="Configure the variable">
        Name your variable `fbp`, enter `_fbp` in the **Cookie Name** field, and click **Save**.
      </Step>

      <Step title="Add to your Google Tag">
        Open your **Google Tag**, click **Add parameter** in the **Event Parameter** field, and enter the parameter `fbp` with the value `{{fbp}}`.
      </Step>

      <Step title="Publish">
        Click **Save** and **Publish** the container.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Using gtag.js">
    1. Define a global function that dynamically gets the cookie value:

       ```javascript theme={null}
       function getFbpCookie() {
         try {
           return /_fbp=(fb\.1\.\d+\.\d+)/.exec(window.document.cookie)[1];
         } catch (e) {
           return undefined;
         }
       }
       ```

       <Warning>
         It is important to use a function instead of saving to a global variable because sometimes the cookie value might not be available yet (for example, the Facebook Pixel SDK has not loaded).
       </Warning>

    2. Add the parameter to your gtag config call:

       ```javascript theme={null}
       gtag('config', 'G-XXXXXXXXXX', {
         fbp: getFbpCookie(),
         // other params...
       });
       ```

    3. **Optional**. Add the parameter to all other events:

       ```javascript theme={null}
       gtag('event', '<EVENT_NAME>', {
         fbp: getFbpCookie(),
         // other params...
       });
       ```

       <Tip>
         Adding parameters to events may improve tracking in case your gtag config call was triggered before cookies were set.
       </Tip>
  </Tab>
</Tabs>


# Google Ads conversions export
Source: https://docs.segmentstream.com/project-configuration/conversions/conversions-export/google-ads-conversions-export

Export SegmentStream conversions to Google Ads for bidding optimization and enhanced conversion tracking.

<Steps>
  <Step title="Select a conversion">
    Inside the admin panel, go to the **Conversions** page and select the conversion that you want to export from the list.
  </Step>

  <Step title="Add export">
    In the conversion menu, click **Add Export**.

    <img alt="Add export button" />
  </Step>

  <Step title="Authenticate with Google Ads">
    Select **Google Ads** in the window that opens and go through the authentication flow.
  </Step>

  <Step title="Configure export settings">
    After the authentication flow, you should see the Google Ads export settings.

    * Select your advertising account and a conversion action that you have created. You can also create a new conversion action by selecting the option in the conversion action dropdown.
    * The attribution window will be set to the value you selected when creating the conversion action, but can be shortened if necessary.
  </Step>

  <Step title="Save">
    Click **Save**. Conversions will be automatically exported to Google Ads daily after data processing for the previous day is completed.
  </Step>
</Steps>

<Info>
  The first conversions will be uploaded at least 6 hours after the conversion is initially created in the Google Ads UI.
</Info>

## Enhanced tracking

Enabling this feature allows SegmentStream to use the **Google Ads Enhanced conversions for leads** feature, an advanced version of offline conversion import. This method leverages user-provided data (such as email addresses) to supplement imported offline conversions, improving both attribution accuracy and bidding performance.

### Information SegmentStream can send

* **ip\_address** (single value, IPv4/IPv6, not available in UK/EU/CH)
* **hashed\_email\_addresses** (SHA256)
* **hashed\_phone\_number** (SHA256)
* **hashed address data** including `hashedFirstName`, `hashedLastName`

<Info>
  To use Enhanced Tracking in SegmentStream, you must first accept **Customer data terms** and enable **Enhanced conversions for leads** in your Google Ads account.
</Info>

### How to enable Enhanced conversions for leads

<Steps>
  <Step title="Open conversion settings">
    In your Google Ads account, go to **Goals** > **Settings**.
  </Step>

  <Step title="Accept customer data terms">
    Expand the **Customer data terms** section and accept the terms.
  </Step>

  <Step title="Enable Enhanced conversions for leads">
    Expand the **Enhanced conversions for leads** section and toggle the feature **On**.
  </Step>

  <Step title="Select data method">
    Select the method for providing user data. If your GA4 is implemented through GTM, choose the corresponding option.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

After completing these steps in Google Ads, enable **Enhanced Tracking** in SegmentStream. It may take up to 10 minutes before SegmentStream allows you to save the Enhanced Tracking conversion export due to Google Ads API delays.

## Retrospective updates

When this feature is enabled, conversions will be updated if their attribution data changes after the initial tracking. This is useful when conversion data is delayed -- for example, when a user makes a purchase online but the transaction is finalized several days later after offline confirmation.

## Use imported conversions for optimization

You can use the imported conversion for bidding optimization at either the account-default or campaign-specific level.

<Tabs>
  <Tab title="Account-default level">
    <Steps>
      <Step title="Navigate to conversions">
        After confirming that data is flowing correctly, go to the **Conversions** section within **Tools & Settings** > **Measurement** in your Google Ads account.
      </Step>

      <Step title="Select the imported conversion">
        Click on the **imported Conversion action** in the list.
      </Step>

      <Step title="Edit settings">
        Click on **Edit settings**.
      </Step>

      <Step title="Set as primary action">
        Expand the **Goal and optimisation action** section and switch the optimisation action to **"Primary action used for bidding optimisation"**.
      </Step>

      <Step title="Save">
        Click **Save**. All campaigns using account-default conversion goals will be optimized toward the imported conversion action.
      </Step>
    </Steps>

    <Warning>
      If you exported a combined SegmentStream conversion, make sure that all website conversions already included in it (for example, Website Purchase) are switched to **Secondary action not used for bidding optimisation** to avoid conversion duplication.
    </Warning>
  </Tab>

  <Tab title="Campaign-specific level">
    <Steps>
      <Step title="Navigate to conversions">
        After confirming that data is flowing correctly, go to the **Conversions** section within **Tools & Settings** > **Measurement** in your Google Ads account.
      </Step>

      <Step title="Add a custom goal">
        Scroll down to the **Custom goals** section, expand it, and click **Add custom goal**.
      </Step>

      <Step title="Configure the custom goal">
        Specify the name and **choose the imported conversion action** from the list. Click **Save**.
      </Step>

      <Step title="Set as campaign goal">
        Navigate to the campaign settings and expand the **Goals** section. Click on **Use campaign-specific goal settings** and choose the custom goal from the list.
      </Step>

      <Step title="Save">
        Click **Save**.
      </Step>
    </Steps>

    <Info>
      You can choose only one custom goal as a campaign-specific goal. If you want to use several custom goals within one campaign, create an additional custom goal for the combination of the needed conversion actions and use it as a campaign-specific goal.
    </Info>
  </Tab>
</Tabs>


# Google Analytics 4 conversions export
Source: https://docs.segmentstream.com/project-configuration/conversions/conversions-export/google-analytics-4-conversions-export

Export SegmentStream conversions to your Google Analytics 4 property for unified reporting.

<Steps>
  <Step title="Select a conversion">
    Inside the admin panel, go to the **Conversions** page and select the conversion you want to export to your GA4 property.
  </Step>

  <Step title="Add export">
    In the conversion menu, click **Add Export**.

    <img alt="Add export button" />
  </Step>

  <Step title="Authenticate with Google Analytics 4">
    Select **Google Analytics 4** in the window that opens and go through the authentication flow.
  </Step>

  <Step title="Configure export settings">
    After the authentication flow, you should see the Google Analytics 4 export settings.

    * Select your **Account**, **Property**, and **Data Stream**.
    * Enter your **Measurement protocol API secret**.
    * Enter the **event name** under which the exported conversions will be reported in the Google Analytics 4 property.
  </Step>

  <Step title="Save">
    Click **Save**. Conversions will be automatically exported to Google Analytics daily after data processing for the previous day is completed.
  </Step>
</Steps>

<Info>
  It might take up to 12 hours before you see the first batch of events from SegmentStream.
</Info>


# LinkedIn conversions export
Source: https://docs.segmentstream.com/project-configuration/conversions/conversions-export/linkedin-conversions-export

Export SegmentStream conversions to your LinkedIn ad account for improved targeting and measurement.

<Steps>
  <Step title="Select a conversion">
    Inside the admin panel, go to the **Conversions** page and select the conversion you want to export to your LinkedIn ad account.
  </Step>

  <Step title="Add export">
    In the conversion menu, click **Add Export**.

    <img alt="Add export button" />
  </Step>

  <Step title="Authenticate with LinkedIn">
    Select **LinkedIn** in the window that opens and go through the authentication flow.
  </Step>

  <Step title="Configure export settings">
    After the authentication flow, you should see the LinkedIn export settings.

    * Select your **LinkedIn Account**.
    * Select the **LinkedIn Conversion** where the conversions will be exported to.
    * Choose whether to enable **Enhanced Tracking**, which exports additional user data such as email, name, and other details if available in the conversion data.
    * Choose whether to enable **Retrospective Updates**, which allows exporting conversions retroactively within the set lookback window. This is useful when conversions are exported from your CRM, particularly when conversions are validated several days after they occur.
  </Step>

  <Step title="Save">
    Click **Save**. Conversions will be automatically exported to LinkedIn daily after data processing for the previous day is completed.
  </Step>
</Steps>

<Info>
  It might take up to 24 hours before you see the first batch of events from SegmentStream within your LinkedIn reports.
</Info>


# Custom conversions
Source: https://docs.segmentstream.com/project-configuration/conversions/custom-conversions

Create conversions using SQL queries against raw BigQuery data for offline or CRM-based conversion tracking.

<Note>
  Custom conversions are available only on the [enterprise plan](https://segmentstream.com/pricing).
</Note>

Custom conversions enable you to create conversions by writing an SQL query that uses any raw data present in your Google BigQuery. A common use case is tracking offline conversions through CRM systems.

Benefits of using custom conversions:

1. They are created and maintained by the SegmentStream technical team.
2. Any data in your BigQuery can be used to calculate conversions.

## Using CRM data

SegmentStream supports data sources for the following CRM tools, allowing you to load data directly into the connected Google BigQuery dataset:

* HubSpot
* Salesforce
* Microsoft Dynamics
* Pipedrive

If you use a different CRM tool, you will need to manually export the CRM data to BigQuery. Alternatively, reach out to your SegmentStream manager for assistance.

## Creating a custom conversion

Each row must include `id` and `created`, plus either a `client_id` (to attribute the conversion to a session directly) or a `lead_id` (to inherit attribution from a parent conversion). `client_id` is required unless the query returns a `lead_id`. Additional columns are optional based on available data.

* The `created` column must always contain a valid timestamp.
* For optional columns, assign `NULL` only if data is occasionally unavailable. If all values for a column are unknown, omit that column from the query.
* If your query involves a partitioned table (for example, partitioned by `date`), include a filter on the partition column in the `WHERE` clause:
  ```sql theme={null}
  WHERE date BETWEEN @start_date AND @end_date
  ```

| SQL field name | Type                                      | Description                                                                                                                                                                                                                                                                                                                                                      | Required    |
| -------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `id`           | STRING                                    | ID of conversion/order used for deduplication                                                                                                                                                                                                                                                                                                                    | Yes         |
| `client_id`    | STRING                                    | Client ID from your analytics tracker (for example, the Google Analytics client ID) used to stitch the conversion to the user's session. Required unless the query returns a `lead_id` (see [Inherit attribution from](#inherit-attribution-from)). If neither resolves, the conversion is marked as (not attributed) in reports.                                | Conditional |
| `created`      | TIMESTAMP                                 | Date and time of the conversion                                                                                                                                                                                                                                                                                                                                  | Yes         |
| `value`        | FLOAT64                                   | The monetary value of the conversion                                                                                                                                                                                                                                                                                                                             | No          |
| `currency`     | STRING                                    | 3-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code (USD, EUR, GBP). If NULL, project currency is used.                                                                                                                                                                                                                          | No          |
| `is_qualified` | BOOLEAN                                   | True if conversion reached target status                                                                                                                                                                                                                                                                                                                         | No          |
| `params`       | ARRAY\<STRUCT\<key STRING, value STRING>> | Array of custom parameters passed with each conversion                                                                                                                                                                                                                                                                                                           | No          |
| `user_id`      | STRING                                    | User's ID from the CRM                                                                                                                                                                                                                                                                                                                                           | No          |
| `lead_id`      | STRING                                    | Matches a record in the parent conversion selected under [Inherit attribution from](#inherit-attribution-from) (by the parent's `id`), so this row inherits the parent's attribution. Use instead of `client_id` when a conversion has no session of its own -- for example a CRM deal that descends from an earlier lead. Required when that option is enabled. | Conditional |

<Tip>
  For lead generation businesses, collecting the conversion value is recommended as it allows SegmentStream to enhance its ML model.
</Tip>

### Collecting geo data from CRM

To improve your market selection options for launching geo tests, consider collecting geo location data in your CRM.

When adding geo data from your CRM, include it in the `params` column as key-value pairs. The `key` should indicate the geographical scope (city, country, or region), while the `value` should specify the name of the geo location.

### Example

After a user purchases a service on your website, they need to confirm their order when contacted by your call centre staff. Once a call centre operator receives confirmation, they update the status in the CRM system.

To view users who have confirmed their purchase in SegmentStream reports, load the data from the CRM system into BigQuery. Then create a custom conversion with SQL that extracts conversions from the CRM data, along with a client identifier used to stitch the conversion to the user's website session.

The following code runs a daily check on website orders created within the last 30 days. It marks them as conversions if their CRM statuses are "confirmed" or "paid", and collects the country, region, and city information.

```sql theme={null}
SELECT
  id,
  userId AS client_id,
  createdAt AS created,
  orderValue AS value,
  'GBP' AS currency,
  IF(orderStatus IN ('confirmed', 'paid'), TRUE, FALSE) AS is_qualified,
  ARRAY(SELECT AS STRUCT * FROM UNNEST(properties) WHERE key IN ('country', 'region', 'city')) AS params
FROM
  `bq-project-id.dataset_id.CRM_order_table_5806956`
WHERE
  date BETWEEN DATE_SUB(@start_date, INTERVAL 30 DAY) AND @end_date
```

<img alt="Custom conversion SQL configuration" />

## Predicted value

You can use a predicted value for your custom conversions. This value is calculated by linking a target conversion's value to the probability of that conversion occurring.

To activate this feature, the `user_id` fields in both the target custom conversion and in any custom conversion for which you want a predicted value should be based on the same identifier. Also, the CRM data that the custom conversion is built on should contain user-related data -- such as geolocation, activities, and any other information particular to that user. This data serves as features for the machine learning model that predicts the value.

When you validate the SQL for your custom conversion, you will find an option called "Predicted value." Choosing this reveals two more fields:

* **Target conversion** -- shows all eligible conversions for value prediction. To qualify, a custom conversion needs the `user_id` field and at least one conversion in the past 60 days.
* **Conversion window** -- sets the maximum timeframe for linking conversions.

Once you save your settings, the ML model calculates the predicted value for each conversion within about 15 minutes.

### Use case

Consider this scenario: you track two types of conversions. The first is called "Lead," which occurs when someone submits a form. The second, "Deal Closed," happens when a lead converts into a deal. Each deal has a unique value.

To estimate the value of each lead, create a modified "Lead" conversion. Enhance the SQL by incorporating CRM data features such as the number of times the user has contacted sales, their business country, and their job title. Set the conversion value to "Predicted value," choose "Deal Closed" as the target conversion, and set the conversion window to 40 days to accommodate the typical duration within which most leads convert into deals.

After SegmentStream completes its calculations, you can view the predicted value of each lead based on the value of the deals that have closed.

<img alt="Predicted value configuration" />

## Inherit attribution from

**Inherit attribution from** lets a conversion borrow its attribution from a parent conversion that already carries the user's journey, instead of attributing itself. This helps in two situations:

* **The conversion has no identifier of its own.** A conversion recorded in a CRM after the on-site session has ended often has no `client_id` to attribute -- but the lead or checkout it descends from does.
* **Long sales cycles.** In a lead -> opportunity -> deal funnel, the click-to-lead gap is short, but the lead-to-deal gap can be 6--12 months. Instead of keeping a 12-month attribution window so each deal can rediscover the original click, attribute the *lead* within a short window and let the deal reuse the lead's attribution.

Each row of the child conversion's SQL returns a `lead_id`; SegmentStream matches it to a record in the parent conversion (by the parent record's `id`), and the child inherits that record's attribution.

### How to enable

1. Add a `lead_id STRING` column to your SQL and re-validate the query. Each value must match the `id` of a record in the parent conversion.
2. Turn on **Inherit attribution from** and select the parent conversion.

<Note>
  The parent must be a Simple, Custom, or Combined conversion in the same project. A conversion cannot inherit from itself, and inheritance chains cannot form a cycle.
</Note>

### How rows are attributed

A row can return both a `client_id` and a `lead_id`. SegmentStream gives each row the best attribution available:

1. **`lead_id` matches a parent record** -- the row inherits the parent's attribution. (If the matched parent is itself unattributed but the row has its own `client_id`, the row keeps its own attribution rather than inheriting "(not attributed)".)
2. **`lead_id` matches no parent** -- the row keeps whatever it resolved on its own: a `client_id` gives it session-based attribution; with no `client_id` it is **(not attributed)**.

Enable **Only track linked conversions** to keep a conversion *only* when its `lead_id` matches a parent record -- unmatched rows are dropped entirely, even if they carry a `client_id`.

### Use case

A B2B funnel runs lead -> opportunity -> deal, and deals can close 6--12 months after the first click. Create a **Lead** conversion (the parent), attributed normally from the on-site form submission. Then build a **Deal** conversion (the child) from your CRM's closed deals that returns `lead_id` = the originating lead's id. Each deal inherits its lead's attribution, so closed-won revenue is credited to the channel that generated the lead -- without keeping a year-long attribution window.

## Conversions adjustment

Enabling conversions adjustment allows you to specify a time window, in days, during which conversion data in SegmentStream can be updated based on changes detected in your CRM. This keeps SegmentStream data aligned with your CRM records.

<img alt="Conversions adjustment settings" />

## BigQuery access issues

If the data from your CRM is exported to a different project than the one specified in the SegmentStream BigQuery settings, provide the SegmentStream service account email with the **BigQuery Data Viewer** and **BigQuery User** roles for that project before setting up custom conversions.


# Conversions FAQ
Source: https://docs.segmentstream.com/project-configuration/conversions/faq

Frequently asked questions about conversions in SegmentStream, including Meta export restrictions and custom conversion troubleshooting.

<AccordionGroup>
  <Accordion title="How does SegmentStream support Meta Conversion Exports for Health and Wellness advertisers?">
    Due to Meta's advertising policy changes, Health and Wellness advertisers are restricted from using bottom-of-funnel events like "Add to Cart" or "Purchase" for campaign optimization. This limits the ability to use standard conversion tracking and value-based bidding strategies.

    SegmentStream addresses this by generating **Synthetic Conversion Events** through Visit Scoring technology. These events are modelled using behavioural signals and predictive analytics to estimate the likelihood and value of a conversion, providing a privacy-compliant and policy-safe alternative to actual purchase events.

    These Synthetic Conversion Events, along with their predicted values, can be exported to Meta via the **Conversions API (CAPI)** and used for **value-based optimization**.

    Although value optimization on custom events is not enabled by default, Meta does offer this functionality as part of a beta program available upon request. Reach out to your Meta representative to have this feature activated on your account.
  </Accordion>

  <Accordion title="Why are my custom conversions not exported to Meta?">
    Meta (Facebook) only accepts event data that occurred **within the last 7 days**. If SegmentStream attempts to send a conversion event that is older than 7 days, Meta rejects the entire request -- not just the outdated event.

    This means that if a conversion happened 8 days ago or earlier, it cannot be exported to Meta. For more details, see [Meta's documentation on offline events](https://developers.facebook.com/docs/marketing-api/conversions-api/offline-events/#2--sending-events).
  </Accordion>
</AccordionGroup>


# Lead Scoring conversions
Source: https://docs.segmentstream.com/project-configuration/conversions/lead-scoring-conversions

Use machine learning to assign quality scores to leads based on their characteristics and likelihood to convert.

<Note>
  Lead Scoring is an enterprise feature that requires collaboration with the SegmentStream data team for implementation and optimization.
</Note>

Lead Scoring is an advanced conversion type that uses machine learning to assign quality scores to your leads based on their characteristics and likelihood to convert. This helps you identify high-value prospects and optimize your marketing spend toward leads that are most likely to generate revenue.

Lead Scoring analyzes your lead data to identify qualified leads and estimates their potential deal value. This allows you to:

* Focus on qualified leads that are most likely to convert
* Optimize marketing campaigns toward lead quality, not quantity
* Improve ROI by focusing budget on channels that generate valuable leads
* Export qualified leads to advertising platforms for better targeting

## Getting started

<Steps>
  <Step title="Assess your data">
    Review whether you have the required lead and sales data.
  </Step>

  <Step title="Choose integration method">
    Determine if you can use a standard CRM integration or need custom data setup.
  </Step>

  <Step title="Contact SegmentStream">
    Reach out to discuss your specific requirements and begin the setup process.
  </Step>
</Steps>

## Data requirements

There are two approaches depending on your CRM setup:

<Tabs>
  <Tab title="Standard CRM integration">
    If you use a well-known CRM system, SegmentStream can automatically connect to your existing data. For example, [HubSpot](/project-configuration/data-sources/hubspot) has a ready-to-use integration.

    Contact your SegmentStream manager to get details about connecting your specific CRM system. With standard CRM integration, SegmentStream automatically collects lead data and deal outcomes to train the scoring model.
  </Tab>

  <Tab title="Custom data integration">
    If you use a custom CRM or one not in the SegmentStream catalog, provide lead and sales data in the following format.

    **Leads data table**

    Required fields:

    | Field              | Description                                          |
    | ------------------ | ---------------------------------------------------- |
    | `created_at`       | When the lead was created                            |
    | `updated_at`       | When the lead was last updated                       |
    | `lead_id`          | Unique identifier for each lead                      |
    | `google_client_id` | Google Analytics Client ID when the lead was created |
    | `user_id`          | Internal user identifier that links to sales data    |

    Include as many relevant lead characteristics as possible to improve model accuracy: email, name, company name, company size, industry, job title, seniority level, lead source, country, annual revenue, budget, pain points, and product interest.

    **Sales/deals data table**

    Required fields:

    | Field        | Description                                 |
    | ------------ | ------------------------------------------- |
    | `created_at` | When the deal was closed                    |
    | `updated_at` | When the deal was last updated              |
    | `order_id`   | Unique identifier for each sale/deal        |
    | `value`      | Revenue amount of the deal                  |
    | `user_id`    | Links back to the lead data (same user\_id) |

    <Warning>
      To accurately predict customer lifetime value, include ALL purchases attributed to each `user_id` in the sales table, not only the first purchase. This helps the model understand the complete revenue potential of similar leads.
    </Warning>
  </Tab>
</Tabs>

## How Lead Scoring works

1. **Data analysis** -- SegmentStream analyzes your historical lead and sales data to identify patterns.
2. **Model training** -- Machine learning models learn which lead characteristics predict successful conversions.
3. **Qualification** -- New leads are evaluated and only those meeting quality thresholds become conversions.
4. **Value prediction** -- The system estimates potential deal value for each qualified lead.
5. **Daily updates** -- Lead qualification and scoring are updated daily as new data becomes available.

## What you get

* **Qualified lead conversions** -- only high-quality leads that meet configurable thresholds are created as conversions in SegmentStream.
* **Predicted deal values** -- estimated revenue potential for each qualified lead.
* **Exportable data** -- qualified lead conversions can be exported to ad platforms such as Google Ads and Meta for enhanced conversions, lookalike audiences, and bid optimization.
* **Reporting and analytics** -- use Lead Scoring conversions in SegmentStream reports to analyze qualified lead performance by traffic source and compare channel effectiveness.

## Best practices

* **Capture Google Client ID** -- ensure your forms capture the Google Analytics Client ID to link website behavior with lead data.
* **Collect rich attributes** -- the more relevant information you collect about leads at the time of creation, the more accurate the scoring will be.
* **Maintain data quality** -- keep lead and sales data clean and up-to-date.
* **Historical data** -- provide at least 6 months of historical data for optimal model training.

<Note>
  Attributes must be available immediately when the lead is created to ensure they can be used for next-day conversion processing. Attributes added later in your sales process may not be available for new lead scoring.
</Note>


# Simple conversions
Source: https://docs.segmentstream.com/project-configuration/conversions/simple-conversions

Track purchase or custom events collected through the SegmentStream tracker as conversions.

Every event you collect through the SegmentStream tracker can be marked as a conversion.

To create a simple conversion, navigate to the **Conversions** page, click **+ ADD**, and select **Simple conversion**.

There are two types of simple conversions: **Purchase** and **Custom event**.

## Purchase

The standard conversion for e-commerce websites. To create this type of conversion, name the conversion (for example, "Purchase"), make sure the Purchase conversion event type is selected, and click **SAVE**.

### Filters

To configure a filter, select from a list of built-in default dimensions, custom dimensions and metrics based on the event parameters collected to your GA4 property, as well as product dimensions.

For example, if you want to track purchases with a total value over \$100, use the **Event Transaction Total** dimension as displayed in the screenshot below.

<img alt="Purchase conversion filter configuration" />

### Conversions deduplication

By default, **Purchase** conversions are deduplicated by order ID. To track only the first purchase per user, enable the **Deduplicate conversions by User** option.

### Conversions adjustment

Enabling conversions adjustment allows you to specify a time window, in days, during which conversion data in SegmentStream can be updated based on refunds processed in GA4. This keeps SegmentStream data aligned with your GA4 reports.

### Normalize by conversion

Adjusts the value of the selected conversion relative to another conversion type (for example, **Purchase**). This helps in benchmarking, scaling, and aligning conversion values to better reflect business impact and optimize attribution.

<img alt="Normalize by conversion setting" />

## Custom event

All events other than the purchase event can be used as conversions through this type. To create this type of conversion, name the conversion (for example, "Lead"), select the Custom conversion event type, and then configure the following sections.

### Filters

To configure a filter, select from a list of built-in default dimensions, custom dimensions and metrics based on the event parameters collected to your GA4 property, as well as product dimensions.

As an example, the **Event Action** dimension values contain the names of the events as they are sent to your GA4 property, so creating a conversion for the event with the **lead** event name would require the setup illustrated in the screenshot below.

### Conversion value

If your conversion has a monetary value that you would like to see in SegmentStream reports, you have two options:

* **Event value** -- useful when the value of each conversion might differ. This requires the `value` event parameter to be configured in the event sent to GA4.
* **Manual value** -- all conversions have an equal value.

If you do not have a monetary value for the conversion, select **No value**.

### Conversions deduplication

Enabling **Deduplicate conversions by User** filters out conversions that happened by users with the same Google Client ID or User ID within a set day window.

### Normalize by conversion

Adjusts the value of the selected conversion relative to another conversion type (for example, **Purchase**). This helps in benchmarking, scaling, and aligning conversion values to better reflect business impact and optimize attribution.

<img alt="Custom event conversion setup" />


# Awin
Source: https://docs.segmentstream.com/project-configuration/data-sources/awin

Connect Awin to SegmentStream and import affiliate cost data.

## Before you begin

You must obtain an API token to provide access to Awin data.

<Steps>
  <Step title="Log in to Awin">
    Login to your [Awin control panel](https://ui.awin.com/login).
  </Step>

  <Step title="Navigate to API credentials">
    Go to the [API credentials section](https://ui.awin.com/awin-api).
  </Step>

  <Step title="Get your API token">
    Enter your account password into the box to display your API token.
  </Step>
</Steps>

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Awin">
    Choose **AWIN** from the list.
  </Step>

  <Step title="Enter API token">
    Paste the **API token** into the input field and click **Save**.
  </Step>

  <Step title="Configure settings">
    Select an **Account**, **Region**, **Time zone** and input the **AWIN commission %**.
  </Step>

  <Step title="Repeat for additional accounts">
    Repeat for all ad accounts whose cost data you would like to import.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM matching for campaigns

SegmentStream supports automatic UTM matching for Awin campaigns only when UTM parameters are defined inside the URL for each offer in your product feed. Otherwise, you will need to match Awin campaigns manually inside the SegmentStream admin panel.

By default, the following matching applies for `utm_source` and `utm_medium`:

* `utm_source` -- `AWIN`
* `utm_medium` -- `Publisher type`

This matching can be changed inside the admin panel by specifying appropriate values for the **UTM source**, **UTM medium mapping**, and **UTM campaign mapping** options.


# Criteo
Source: https://docs.segmentstream.com/project-configuration/data-sources/criteo

Connect Criteo to SegmentStream and import campaign cost data.

## Before you begin

Make sure you have **Admin** rights for the Criteo Account.

<Steps>
  <Step title="Go to Criteo Partners">
    Go to [partners.criteo.com](https://partners.criteo.com/).
  </Step>

  <Step title="Create an Organization">
    Create a new Organization if it is not already created.
  </Step>

  <Step title="Create a new App">
    Click the **Create New App** button.
  </Step>

  <Step title="Fill in app details">
    Fill in the **Name** and the **Description** fields and click **Next**.
  </Step>

  <Step title="Choose authentication method">
    Select **Client credentials** as the authentication method.
  </Step>

  <Step title="Select services">
    In the **Service** section, choose **C-Growth** and **Marketing Solutions** and click **Next**.
  </Step>

  <Step title="Set authorizations">
    In the **Authorizations** section, choose the **Read** value for every Domain in the row and click **Activate app**.
  </Step>

  <Step title="Create API key">
    Scroll to the **App Credentials** section and click the **Create new key** button. The browser will download a text file with the API credentials.
  </Step>

  <Step title="Generate consent URL">
    Click **Generate new URL** in the right upper corner.
  </Step>

  <Step title="Grant portfolio access">
    Click **Generate URL** and copy-paste it in the address bar of the browser. Scroll to the **Portfolio Access** section, choose the **Account name** and click **Ok**.
  </Step>
</Steps>

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Criteo">
    Choose **Criteo** from the list.
  </Step>

  <Step title="Enter API credentials">
    Open the downloaded file with the API credentials and copy-paste the **Client ID** and **Client Secret**.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

Adding a `utm_id` parameter to your tagging template will guarantee improved stitching quality of costs to sessions without altering the rest of your existing UTM tags.

<Steps>
  <Step title="Navigate to Ad Set tracking">
    Go to your **Ad Set** and navigate to the **Ads Tracking** option.
  </Step>

  <Step title="Add the utm_id parameter">
    In the **Track clicks** section, find the **Tracking suffix** field, and append the following parameter that uses [URL macros](https://help.criteo.com/kb/guide/en/about-ad-tracking-YxbuNl0Ddg/Steps/775660,1139312):

    ```plain text theme={null}
    &utm_id={{criteo_campaignid}}_{{adsetid}}_{{adid}}
    ```
  </Step>

  <Step title="Save">
    Click **Save and continue**.
  </Step>
</Steps>

For a detailed guide on how to set up ad tracking, refer to the [Criteo documentation](https://help.criteo.com/kb/guide/en/about-ad-tracking-YxbuNl0Ddg/Steps/775660,1139194).

## Manual UTM matching for campaigns

If the SegmentStream automatic UTM matching does not result in optimal ad cost to session stitching, you will need to match Criteo campaigns manually inside the SegmentStream admin panel.

By default, the following matching applies for `utm_source` and `utm_medium`:

* `utm_source` -- `criteo`
* `utm_medium` -- `cpc`

This matching can be changed inside the admin panel by specifying appropriate values for the **UTM source** and **UTM medium** options.

For all your Criteo campaigns, you need to define matching between the **Campaign ID** and **UTM campaign**.

For example, if you have a Criteo campaign with the **Campaign ID** = `Lower Funnel` with the following link to the website: `http://www.site.com/?utm_source=criteo&utm_medium=retargeting&utm_campaign=lower_funnel`, the mapping should use `lower_funnel` as the UTM campaign value.


# Facebook
Source: https://docs.segmentstream.com/project-configuration/data-sources/facebook

Connect Facebook Ads to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Facebook">
    Choose **Facebook** from the list.
  </Step>

  <Step title="Authenticate">
    Click **Authenticate with Facebook** and go through the authentication flow.
  </Step>

  <Step title="Select accounts">
    Select the accounts you would like to connect.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

Adding a `utm_id` parameter to your tagging template will guarantee improved stitching quality of costs to sessions without altering the rest of your existing UTM tags.

We suggest using the following format for the `utm_id` parameter in Facebook ads:

```plain text theme={null}
utm_id={{campaign.id}}_{{adset.id}}_{{ad.id}}
```

Once the `utm_id` parameter is implemented, sessions will be stitched with costs at the ad level. The Campaign, Ad Group, and Ad Name dimensions of the SegmentStream reports will display the Facebook campaign name, ad set name, and ad name, respectively.

## Supported dynamic URL parameters

By default Facebook allows the use of [dynamic URL tagging parameters](https://www.facebook.com/business/help/2360940870872492) to track campaigns.

SegmentStream supports the following parameters:

| Name                   | Description                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `{{ad.id}}`            | The unique ID of the ad.                                                                                                                                                                                                                                                                                                                                                                               |
| `{{adset.id}}`         | The unique ID of the ad set. An ad set is a group of ads that share the same budget, schedule, delivery optimisation and targeting.                                                                                                                                                                                                                                                                    |
| `{{campaign.id}}`      | The unique ID number of the ad campaign. A campaign contains ad sets and ads.                                                                                                                                                                                                                                                                                                                          |
| `{{ad.name}}`          | The name of the ad.                                                                                                                                                                                                                                                                                                                                                                                    |
| `{{adset.name}}`       | The name of the ad set. An ad set is a group of ads that share the same budget, schedule, delivery optimisation and targeting.                                                                                                                                                                                                                                                                         |
| `{{campaign.name}}`    | The name of the ad campaign. A campaign contains ad sets and ads.                                                                                                                                                                                                                                                                                                                                      |
| `{{site_source_name}}` | Depending on where the ad appeared this parameter has four possible values: `fb` (Facebook), `ig` (Instagram), `msg` (Messenger), `an` (Audience Network).                                                                                                                                                                                                                                             |
| `{{placement}}`        | Depending on where the ad appeared this parameter has possible values: `Facebook_Mobile_Feed`, `Facebook_Right_Column`, `Facebook_Instant_Articles`, `Facebook_Instream_Video`, `Facebook_Marketplace`, `Instagram_Stories`, `Instagram_Feed`, `Instagram_Explore`, `Messenger_Inbox`, `Messenger_Stories`, `Facebook_Desktop_Feed`, `an` (for Audience Network), `Others` (for all other placements). |

## Sharing access with SegmentStream

To help SegmentStream perform quality checks and validate data, you can share view-only access to your Facebook Ads account.

<Steps>
  <Step title="Open Business Manager">
    Open Facebook Business Manager and go to **Accounts** > **Ad accounts**.
  </Step>

  <Step title="Assign Partner">
    Select the ad account you want to share and click **Assign Partner**.
  </Step>

  <Step title="Enter SegmentStream business ID">
    Enter SegmentStream's business ID: **843884825767231**.
  </Step>

  <Step title="Set permissions">
    Select **View Performance** for view-only access, then click **Assign**.
  </Step>
</Steps>

Your Facebook Ad Account is now shared with SegmentStream.


# Data sources FAQ
Source: https://docs.segmentstream.com/project-configuration/data-sources/faq

Frequently asked questions about connecting data sources to SegmentStream.

<AccordionGroup>
  <Accordion title="Should we change UTM parameters in our Facebook campaigns?">
    You have the flexibility to use any UTM parameters that suit your tracking needs. However, for better data accuracy and to prevent potential problems should you decide to rename your campaign or change the `utm_campaign` parameter, we recommend adding a `utm_id` to each of your tracking URLs. This can make data analysis more precise. For more detailed information on how to implement this, refer to the [Facebook data source guide](/project-configuration/data-sources/facebook).
  </Accordion>

  <Accordion title="Data in my ad platform cabinet doesn't exactly match data in SegmentStream reports">
    Occasionally, the data displayed in your reports may not match what you see in the ad platform. This can happen because the ad platform sometimes makes retrospective updates to the data after SegmentStream has loaded it into the reports. To address this, SegmentStream has a feature that detects significant differences of more than 5% in exported metrics. When such differences occur, SegmentStream automatically reloads the data to minimise discrepancies and provide you with the most accurate insights possible.
  </Accordion>
</AccordionGroup>


# Google Ads
Source: https://docs.segmentstream.com/project-configuration/data-sources/google-ads

Connect Google Ads to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Google Ads">
    Choose **Google Ads** from the list.
  </Step>

  <Step title="Authenticate">
    Click **Authenticate with Google** and go through the authentication flow.
  </Step>

  <Step title="Select accounts">
    Select the manager or individual Google Ads advertising accounts you would like to connect.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## Manager advertising accounts

By default, both [manager](https://support.google.com/google-ads/answer/6139186) and individual advertising accounts are available for data import. If you select a manager account, all associated individual accounts will be automatically connected as well.

## UTM tagging best practices

SegmentStream uses the Google Click ID (GCLID) to link sessions to ad cost data. However, in some cases, the GCLID may be unavailable due to [privacy issues](https://support.google.com/analytics/answer/11367152?hl=en). In such cases, you can link sessions by adding the `utm_source`, `utm_medium`, and `utm_id` parameters to your tracking template.

We suggest using the following format in the Google Ads account-level tracking template:

```plain text theme={null}
{lpurl}?utm_source=google&utm_medium=cpc&utm_id={campaignid}_{adgroupid}_{assetgroupid}_{creative}
```

For instructions on how to edit your tracking template, refer to the [Google Ads documentation](https://support.google.com/google-ads/answer/10070427).

<Warning>
  To ensure proper allocation of costs for your ad extension clicks (such as sitelink extensions, price extensions, promotion extensions, etc.), avoid defining UTM parameters at the Ad or Ad Extension level. Instead, define your UTM parameters at the Account, Campaign, or Ad Group level.
</Warning>

## Supported dynamic URL parameters

By default Google Ads allows the use of [dynamic URL tagging parameters](https://support.google.com/google-ads/answer/6305348) to track campaigns.

SegmentStream supports the following parameters:

| Name                | Description                                                                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{lpurl}`           | The final URL. It will be escaped unless you put `{lpurl}` at the beginning of your tracking template.                                                                             |
| `{gclid}`           | The Google click identifier of a click that comes from your ad.                                                                                                                    |
| `{campaignid}`      | The campaign ID. Use this when you've set up your tracking info at account level and want to know which campaign served your ad.                                                   |
| `{adgroupid}`       | The ad group ID. Use this when you've set up your tracking info at the account or campaign level and want to know which ad group served your ad.                                   |
| `{assetgroupid}`    | The asset group ID. Use this when you want to know which asset group served your ad, for example in Performance Max campaigns.                                                     |
| `{targetid}`        | The ID of the keyword (`kwd`), dynamic search ad (`dsa`) target, remarketing list target (`aud`), product partition (`pla`) or hotel group partition (`hpi`) that triggered an ad. |
| `{creative}`        | A unique ID for your ad.                                                                                                                                                           |
| `{network}`         | Where the click came from: `g` for Google search, `s` for a search partner, or `d` for the Display Network.                                                                        |
| `{keyword}`         | For the Search Network: the keyword from your account that matches the search query. For the Display Network: the keyword from your account that matches the content.              |
| `{loc_interest_ms}` | The ID of the location of interest that helped to trigger the ad. Reported only for campaigns that show ads to people searching for your targeted locations.                       |
| `{loc_physical_ms}` | The ID of the geographical location of the click. Reported only for campaigns that show ads to people in your targeted locations.                                                  |
| `{matchtype}`       | The match type of the keyword that triggered your ad: `e` for exact, `p` for phrase, or `b` for broad.                                                                             |
| `{device}`          | The type of device that the click came from: `m` for mobile (including WAP), `t` for tablet, and `c` for computer.                                                                 |

<Note>
  If you use unsupported parameters in UTM tags, you will see the parameter names instead of their values (for example, `{source}` instead of `search.google.com`). Move unsupported parameters from UTM tags to additional custom GET parameters and collect them to custom dimensions in Google Analytics.
</Note>

## Sharing access with SegmentStream

To help SegmentStream perform quality checks and validate data, you can share view-only access to your Google Ads account. Contact the support team at [support@segmentstream.com](mailto:support@segmentstream.com) with your Google Ads Account ID(s), and a linking request will be sent from the MCC for troubleshooting access.


# Google Display & Video 360
Source: https://docs.segmentstream.com/project-configuration/data-sources/google-dv360

Connect Google Display & Video 360 to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Google DV360">
    Choose **Google Display & Video 360** from the list.
  </Step>

  <Step title="Authenticate">
    Click **Click to authenticate with Google** and go through the authentication and setup flow.
  </Step>

  <Step title="Name the data source">
    Name your data source.
  </Step>

  <Step title="Select partner and advertisers">
    Select the partner and advertisers from which you would like to import cost data.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

Adding a `utm_id` parameter to your tagging template will guarantee improved stitching quality of costs to sessions without altering the rest of your existing UTM tags.

We suggest using the following format for the `utm_id` parameter in Display & Video 360 ads:

```plain text theme={null}
utm_id={ID of the campaign}_{ID of the line item}
```

The tagging can be implemented using [URL macros](https://support.google.com/displayvideo/answer/2789508?hl=en).

## UTM matching for Youtube & partners ads

SegmentStream does not support automatic UTM matching for [Youtube & partners ads](https://support.google.com/displayvideo/answer/6274216?hl=en).

You can define the default `utm_source` and `utm_medium` for all these ads through the **UTM source for YouTube & partners ads** and **UTM medium for YouTube & partners ads** settings. SegmentStream will use the campaign name of those ads to match by `utm_campaign`.

The following setup will help improve cost data stitching and will allow seeing costs at campaign level for Youtube & partners ads:

```plain text theme={null}
utm_source=youtube&utm_medium=cpm&utm_campaign={campaign name in the DV360 interface}
```


# Google Sheets
Source: https://docs.segmentstream.com/project-configuration/data-sources/google-sheets

Import cost data into SegmentStream from Google Sheets for any advertising platform.

Using Google Sheets as a data source is a universal way to import any type of data even if you did not find an appropriate data source inside the SegmentStream admin panel.

## Creating a costs sheet

To import costs into SegmentStream, you need to create a Google Sheet where the data is listed in the following format.

<Tip>
  Use [this template](https://docs.google.com/spreadsheets/d/1TBiJkySz7BfAzVbEq3KyMzNkLJDKqE0DhG5ECyDAGQU/edit#gid=0) for daily costs.
</Tip>

| Name        | Type    | Required     | Description                                                                        | Example             |
| ----------- | ------- | ------------ | ---------------------------------------------------------------------------------- | ------------------- |
| date        | DATE    | **required** | Reporting date in `YYYY-MM-DD` format                                              | 2020-04-03          |
| currency    | STRING  | **required** | Currency code                                                                      | USD                 |
| cost        | FLOAT   | **required** | Total spendings for the reporting date                                             | 460.5               |
| impressions | INTEGER | optional     | Total number of impressions during the day                                         | 12500               |
| clicks      | INTEGER | optional     | Total number of clicks during the day                                              | 284                 |
| utmMedium   | STRING  | **required** | `utm_medium` URL parameter attributed to the costs entry                           | cpa                 |
| utmSource   | STRING  | **required** | `utm_source` URL parameter attributed to the costs entry                           | partner1            |
| utmCampaign | STRING  | optional     | `utm_campaign` URL parameter attributed to the costs entry                         | campaign1           |
| utmTerm     | STRING  | optional     | `utm_term` URL parameter attributed to the costs entry                             | black\_shoes        |
| utmContent  | STRING  | optional     | `utm_content` URL parameter attributed to the costs entry                          | bottom\_cta\_button |
| campaign    | STRING  | optional     | The name of the campaign as it will be reported inside SegmentStream               | Example Campaign    |
| campaignId  | STRING  | optional     | The ID of the campaign that will allow SegmentStream to match it to URL parameters | 123123              |

## Monthly costs import

Sometimes it might be required to import monthly costs (subscriptions, salaries) and attribute them to a specific set of UTM parameters, for example:

* SEO costs
* CDP/ESP costs
* PR costs

<Tip>
  Use [this template](https://docs.google.com/spreadsheets/d/1tBYrGf7PcXvTQqxBKsnwxc-aojgcRLJft9VMXwKt86E/edit#gid=0) for uploading monthly costs.
</Tip>

For example, if you spent \$3000 each month of the first quarter of 2024 on your favorite ESP platform and would like to attribute these costs to `utm_source=my_esp` and `utm_medium=email`, you can structure your sheet as follows:

| month      | currency | cost | impressions | clicks | utmSource | utmMedium |
| ---------- | -------- | ---- | ----------- | ------ | --------- | --------- |
| 2024-01-01 | USD      | 3000 |             |        | email     | my\_esp   |
| 2024-02-01 | USD      | 3000 |             |        | email     | my\_esp   |
| 2024-03-01 | USD      | 3000 |             |        | email     | my\_esp   |

## Enabling Google Sheets data source

<Steps>
  <Step title="Navigate to Data Sources">
    Go to the [SegmentStream admin panel](https://app.segmentstream.com/). Go to the **Data Sources** section and click **+ NEW**.
  </Step>

  <Step title="Select Google Sheets">
    Select **Google Sheets**.
  </Step>

  <Step title="Authenticate">
    Click **Authenticate with Google** and go through the authentication flow.
  </Step>

  <Step title="Enter spreadsheet URL">
    In the **Google Spreadsheet URL** field specify the URL of the sheet that you want to import.
  </Step>

  <Step title="Select report type">
    Select the **Daily cost data group by UTM** or **Monthly cost data grouped by UTM** report type.
  </Step>

  <Step title="Set destination table">
    In the **Destination table name** field specify a unique BigQuery table name where you would like to store the data imported from the specified sheet, for example, `daily_costs_platform_name`.
  </Step>
</Steps>

## Custom Google Sheets report type

Custom Google Sheets report types allow you to upload data that requires additional processing before being used in SegmentStream reports. Before using this feature, contact your SegmentStream manager.

To enable a custom Google Sheets upload, follow steps 1 through 5 from the previous section, then:

1. Select **Custom** report type.
2. Map sheet columns to proper data types:
   * **date** -> `DATE`
   * **cost** -> `FLOAT`
   * **impressions** -> `INTEGER`
   * **clicks** -> `INTEGER`

By default, all other columns will be imported as **String**.

## What's next

During the next 24 hours your data will be uploaded to the corresponding BigQuery table.


# Hubspot
Source: https://docs.segmentstream.com/project-configuration/data-sources/hubspot

Connect Hubspot to SegmentStream and import CRM data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Hubspot">
    Choose **Hubspot** from the list.
  </Step>

  <Step title="Authenticate">
    Click **Authenticate** and go through the authentication flow.
  </Step>

  <Step title="Select reports">
    Select the reports you would like to export. SegmentStream supports the export of the [contacts](https://developers.hubspot.com/docs/api/crm/contacts) and [deals](https://developers.hubspot.com/docs/api/crm/deals) reports.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>


# impact.com
Source: https://docs.segmentstream.com/project-configuration/data-sources/impact

Connect impact.com to SegmentStream and import affiliate cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select impact.com">
    Choose **impact.com** from the list.
  </Step>

  <Step title="Enter API credentials">
    Enter the **Account SID** and **Auth Token** API credentials and click **Save**. You can find your credentials in your [impact.com](https://app.impact.com/) account settings by navigating to the vertical ellipsis menu > **Settings** > **API**. Read Only permissions are sufficient to export cost data.
  </Step>

  <Step title="Select advertising accounts">
    Select your **Advertising accounts**.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## Supported dynamic URL parameters

By default impact.com supports a list of [dynamic URL tracking parameters](https://integrations.impact.com/impact-brand/docs/branch#section-link-parameters-reference) to track campaigns.

SegmentStream supports the following parameters:

| Name         | Description                       |
| ------------ | --------------------------------- |
| `{irmpname}` | Name of the impact.com partner.   |
| `{ircid}`    | Your impact.com Program ID value. |


# LinkedIn
Source: https://docs.segmentstream.com/project-configuration/data-sources/linkedin

Connect LinkedIn Ads to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select LinkedIn">
    Choose **LinkedIn** from the list.
  </Step>

  <Step title="Authenticate">
    Click **Authenticate with LinkedIn** and go through the authentication flow.
  </Step>

  <Step title="Select accounts">
    Select the accounts you would like to connect.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

Adding a `utm_id` parameter to your tagging template will guarantee improved stitching quality of costs to sessions without altering the rest of your existing UTM tags.

<Steps>
  <Step title="Open URL parameters">
    In the left side menu, select **Account settings** > **URL parameters**.
  </Step>

  <Step title="Add tracking parameters">
    Add the following to the **Account tracking parameters** field:

    ```plain text theme={null}
    utm_id={{CAMPAIGN_ID}}&utm_campaign={{CAMPAIGN_NAME}}&utm_content={{CREATIVE_ID}}&utm_source=linkedin&utm_medium=paid-social
    ```
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

Once the `utm_id` parameter is implemented, sessions will be stitched with costs at the ad level. The Campaign and Ad Group dimensions of the SegmentStream reports will display the LinkedIn campaign name and campaign group name, respectively.


# Microsoft Advertising
Source: https://docs.segmentstream.com/project-configuration/data-sources/microsoft-ads

Connect Microsoft Advertising to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Microsoft Advertising">
    Choose **Microsoft Advertising** from the list.
  </Step>

  <Step title="Authenticate">
    Click **Authenticate with Microsoft** and go through the authentication flow.
  </Step>

  <Step title="Select account">
    Select the advertising account you would like to connect.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

Adding a `utm_id` parameter to your ads URLs will guarantee improved stitching quality of costs to sessions without altering the rest of your existing UTM tags.

<Steps>
  <Step title="Open account-level options">
    In the left side menu, select **Campaigns** > **Settings** > **Account level options**.
  </Step>

  <Step title="Add the utm_id parameter">
    Add `utm_id={CampaignId}_{AdGroupId}_{AdId}` in the **Final URL suffix** field.
  </Step>

  <Step title="Test">
    Click **Test** to check if the URL contains the `utm_id` parameter.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

Once the `utm_id` parameter is implemented, sessions will be stitched with costs at the ad level. The Campaign, Ad Group, and Ad Name dimensions of the SegmentStream reports will display the Microsoft Advertising campaign name, ad group name, and ad name, respectively.

## Supported dynamic URL parameters

By default Microsoft Advertising allows the use of [dynamic URL tracking parameters](https://help.ads.microsoft.com/#apex/3/en/56799/2) to track campaigns.

SegmentStream supports the following parameters:

| Name             | Description                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{lpurl}`        | The final URL. It will be escaped unless you put `{lpurl}` at the beginning of your tracking template.                                                  |
| `{CampaignId}`   | The ID of the campaign that triggered the ad.                                                                                                           |
| `{Campaign}`     | The name of the campaign that triggered the ad.                                                                                                         |
| `{AdGroupId}`    | The ID of the ad group that triggered the ad.                                                                                                           |
| `{AdGroup}`      | The name of the ad group that triggered the ad.                                                                                                         |
| `{MatchType}`    | The match type used to deliver an ad: `e` for exact, `p` for phrase, `b` for broad. Expanded match is treated as broad match.                           |
| `{BidMatchType}` | The keyword bid match type: `be` for bidded exact, `bp` for bidded phrase, `bb` for bidded broad.                                                       |
| `{Network}`      | The ad network type: `o` for owned and operated (Bing, AOL, Yahoo), `s` for syndicated (search partner), `a` for audience (Microsoft Audience Network). |
| `{Device}`       | The device type: `m` for mobile, `t` for tablet, `c` for desktop or laptop.                                                                             |
| `{AdId}`         | The numeric ID of the displayed ad.                                                                                                                     |
| `{keyword}`      | The keyword that matched the user's search term.                                                                                                        |

<Note>
  If you use unsupported parameters in UTM tags, you will see the parameter names in SegmentStream reports instead of their values (for example, `{OrderItemId}` instead of `1234567890`). For better stitching quality, move unsupported parameters from UTM tags to additional custom GET parameters.
</Note>


# OpenAI Ads
Source: https://docs.segmentstream.com/project-configuration/data-sources/openai-ads

Connect OpenAI Ads to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Generate an API token in OpenAI Ads">
    In your OpenAI Ads Manager, generate an API token that has read access to your ad account. Each OpenAI Ads token is scoped to a single ad account — if you manage several accounts, generate one token per account and connect them as separate data sources.
  </Step>

  <Step title="Navigate to Data Sources">
    Inside the SegmentStream admin panel, navigate to the **Data Sources** page and click **+ NEW** in the top-right corner.
  </Step>

  <Step title="Select OpenAI Ads">
    Choose **OpenAI Ads** from the list.
  </Step>

  <Step title="Enter your API token">
    Paste the token into the **OpenAI Ads API token** field and continue.
  </Step>

  <Step title="Confirm the ad account">
    The **Ad account** dropdown auto-populates from the token. Select it and click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

SegmentStream reads UTM parameters from the final URL served to visitors — that is, the ad's **Target URL** combined with the campaign-level and ad-level **Query string templates**. For campaigns, ad groups, and ads to stitch correctly to sessions, your OpenAI Ads templates must include the standard `utm_*` parameters.

The connector supports OpenAI Ads' template macros for per-row substitution:

| Macro             | Substituted with  |
| ----------------- | ----------------- |
| `{ad_account_id}` | The ad account ID |
| `{campaign_id}`   | The campaign ID   |
| `{ad_group_id}`   | The ad group ID   |
| `{ad_id}`         | The ad ID         |

<Steps>
  <Step title="Open the query string template">
    In OpenAI Ads Manager, open the campaign or ad settings where the query string template is configured.
  </Step>

  <Step title="Add tracking parameters">
    Add the following to the template:

    ```plain text theme={null}
    utm_source=openai&utm_medium=cpc&utm_campaign={campaign_id}&utm_content={ad_id}
    ```

    Ad-level template values take precedence over campaign-level values on the same key. UTMs the advertiser puts directly on the ad's **Target URL** take precedence over any template values.
  </Step>

  <Step title="Save">
    Save the template. Newly served ads will start carrying the parameters immediately; already-live ads pick them up on the next refresh.
  </Step>
</Steps>

Once the template is in place, sessions will be stitched with costs at the ad level. The **Campaign** and **Ad** dimensions in SegmentStream reports will display the OpenAI Ads campaign name and ad name.

<Tip>
  If spend loads into your reports but campaigns don't appear alongside sessions, check that the query string template is applied and that `utm_source`, `utm_medium`, and `utm_campaign` all resolve to non-empty values on live ads.
</Tip>


# Data sources
Source: https://docs.segmentstream.com/project-configuration/data-sources/overview

Connect advertising platforms and data warehouses to SegmentStream to view campaign performance data in reports.

To see how well your online advertising and marketing campaigns are performing, you can connect your advertising platforms to SegmentStream. This allows you to view campaign performance data in SegmentStream reports. You can also import CRM, offline conversion, and other business data from a data warehouse alongside your ad-platform data. Everything lands in BigQuery and is available in SegmentStream reports.

## Connecting a data source

<Steps>
  <Step title="Navigate to Data Sources">
    Go to the **Data Sources** page in the **Settings** section of the admin panel.
  </Step>

  <Step title="Select the data source">
    Select the data source that you wish to connect.
  </Step>

  <Step title="Authenticate">
    Complete the authorisation process to allow SegmentStream to collect ad platform data.
  </Step>

  <Step title="Pick accounts">
    Pick the accounts you want to connect through the data source.
  </Step>

  <Step title="Name and save">
    Provide a unique name for your data source and click **Save**.
  </Step>
</Steps>

<img alt="Connecting a data source in the admin panel" />

## Available integrations

<CardGroup>
  <Card title="Facebook" icon="meta" href="/project-configuration/data-sources/facebook">
    Import cost data from Facebook Ads.
  </Card>

  <Card title="Google Ads" icon="google" href="/project-configuration/data-sources/google-ads">
    Import cost data from Google Ads.
  </Card>

  <Card title="Microsoft Advertising" icon="microsoft" href="/project-configuration/data-sources/microsoft-ads">
    Import cost data from Microsoft Advertising.
  </Card>

  <Card title="LinkedIn" icon="linkedin" href="/project-configuration/data-sources/linkedin">
    Import cost data from LinkedIn Ads.
  </Card>

  <Card title="TikTok" icon="tiktok" href="/project-configuration/data-sources/tiktok">
    Import cost data from TikTok Ads.
  </Card>

  <Card title="RTB House" icon="rectangle-ad" href="/project-configuration/data-sources/rtb-house">
    Import cost data from RTB House.
  </Card>

  <Card title="Pinterest" icon="pinterest" href="/project-configuration/data-sources/pinterest">
    Import cost data from Pinterest Ads.
  </Card>

  <Card title="Criteo" icon="rectangle-ad" href="/project-configuration/data-sources/criteo">
    Import cost data from Criteo.
  </Card>

  <Card title="Google DV360" icon="google" href="/project-configuration/data-sources/google-dv360">
    Import cost data from Google Display & Video 360.
  </Card>

  <Card title="Twitter (X Ads)" icon="x-twitter" href="/project-configuration/data-sources/x-ads">
    Import cost data from X Ads.
  </Card>

  <Card title="Awin" icon="handshake" href="/project-configuration/data-sources/awin">
    Import cost data from Awin.
  </Card>

  <Card title="impact.com" icon="handshake" href="/project-configuration/data-sources/impact">
    Import cost data from impact.com.
  </Card>

  <Card title="Google Sheets" icon="table" href="/project-configuration/data-sources/google-sheets">
    Import cost data from Google Sheets.
  </Card>

  <Card title="Reddit" icon="reddit" href="/project-configuration/data-sources/reddit">
    Import cost data from Reddit Ads.
  </Card>

  <Card title="Snapchat" icon="snapchat" href="/project-configuration/data-sources/snapchat">
    Import cost data from Snapchat Ads.
  </Card>

  <Card title="StackAdapt" icon="rectangle-ad" href="/project-configuration/data-sources/stackadapt">
    Import cost data from StackAdapt.
  </Card>

  <Card title="OpenAI Ads" icon="robot" href="/project-configuration/data-sources/openai-ads">
    Import cost data from OpenAI Ads.
  </Card>

  <Card title="Hubspot" icon="hubspot" href="/project-configuration/data-sources/hubspot">
    Import CRM data from Hubspot.
  </Card>
</CardGroup>

## Other supported platforms

The following platforms are also available as data sources through the admin panel. They follow the standard connection process and do not require additional configuration steps:

* AdRoll
* Google Campaign Manager
* OutBrain
* Quora
* Microsoft Dynamics 365
* Pipedrive
* Salesforce
* Appsflyer
* JSON Feed
* Webhook

## Data warehouses

Import arbitrary tables or query results from a data warehouse into your project's BigQuery dataset. Use these to enrich SegmentStream reports with CRM data, offline conversions, product catalogues, or anything else that lives in your warehouse.

<CardGroup>
  <Card title="Snowflake" icon="snowflake" href="/project-configuration/data-sources/snowflake">
    Run a SQL query against a Snowflake warehouse on a daily schedule and load the results into a BigQuery table you choose.
  </Card>
</CardGroup>

## Best practices

If you run campaigns for multiple websites using one account, you can filter out unwanted websites from reports using the data source filters. This feature works for Google Ads, Facebook Ads, TikTok, and Microsoft Ads. Adjust the settings in each data source, and the changes will reflect in reports the next day.

<img alt="Data source filter settings" />

## Untracked clicks

When SegmentStream detects that clicks from a campaign in a connected ad platform data source cannot be matched with any sessions on the website, it generates a notification to highlight this issue.

This typically occurs when the URLs used in your ads lack the required tracking parameters or when certain sections of your website do not have proper or complete implementation of the tracking code.

## FAQ

If you have questions about data sources, check the [Data sources FAQ](/project-configuration/data-sources/faq).

Contact the support team if you need help connecting a data source.


# Pinterest
Source: https://docs.segmentstream.com/project-configuration/data-sources/pinterest

Connect Pinterest Ads to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Pinterest">
    Choose **Pinterest** from the list.
  </Step>

  <Step title="Authenticate">
    Click **Click to connect Pinterest** and go through the authentication and setup flow.
  </Step>

  <Step title="Name the data source">
    Name your data source.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

Adding a `utm_id` parameter to your tagging template will guarantee improved stitching quality of costs to sessions without altering the rest of your existing UTM tags.

<Steps>
  <Step title="Append the utm_id parameter">
    In the **Destination URL** field of your ad setup, append the following parameter to your URL:

    ```plain text theme={null}
    &utm_id={campaignid}_{adid}
    ```
  </Step>

  <Step title="Publish">
    Click **Publish**.
  </Step>
</Steps>

## Shopping campaigns settings

SegmentStream does not support automatic UTM matching for [Shopping campaigns](https://help.pinterest.com/en/business/article/track-report-optimize-shopping-campaigns). You will need to match these types of campaigns manually inside the SegmentStream admin panel using the following settings.

### URL parameters for all Shopping campaigns

If you use a single UTM tracking template for all Shopping campaigns in your Pinterest account, enter it into this field to ensure proper allocation of cost to sessions in the reports.

### URL parameters for specific Shopping campaigns

If specific Shopping campaigns in your Pinterest account use unique UTM tracking templates, enter the respective **Campaign ID** and **URL parameters** to ensure that the cost is properly allocated to sessions for those campaigns.

## Supported dynamic URL parameters

By default Pinterest allows the use of [dynamic URL tagging parameters](https://help.pinterest.com/en/business/article/third-party-and-dynamic-tracking) to track campaigns.

SegmentStream supports the following parameters:

| Name              | Description                |
| ----------------- | -------------------------- |
| `{campaignid}`    | Advertising campaign ID.   |
| `{campaign_name}` | Advertising campaign name. |
| `{adgroupid}`     | Ad group ID.               |
| `{adgroup_name}`  | Ad group name.             |
| `{creative_id}`   | Pin promotion ID.          |
| `{adid}`          | Pin promotion ID.          |


# Reddit
Source: https://docs.segmentstream.com/project-configuration/data-sources/reddit

Connect Reddit Ads to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Reddit">
    Choose **Reddit** from the list.
  </Step>

  <Step title="Authenticate">
    Click **Click to connect with Reddit** and go through the authentication and setup flow.
  </Step>

  <Step title="Select account">
    Select the account from which you would like to import the cost data.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

Append the following `utm_id` parameter using [Reddit macros](https://business.reddithelp.com/helpcenter/s/article/Set-up-third-party-measurement) to your Destination URL to ensure the best stitching quality for your ads:

```plain text theme={null}
&utm_id={{CAMPAIGN_ID}}_{{ADGROUP_ID}}_{{AD_ID}}
```


# RTB House
Source: https://docs.segmentstream.com/project-configuration/data-sources/rtb-house

Connect RTB House to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select RTB House">
    Choose **RTB House** from the list.
  </Step>

  <Step title="Authenticate">
    Authenticate using your RTB House **Username** and **Password**.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM matching for campaigns

SegmentStream supports automatic UTM matching for RTB House campaigns only when UTM parameters are defined inside the URL for each offer in your product feed. Otherwise, you will need to match RTB House campaigns manually inside the SegmentStream admin panel.

By default, the following matching applies for `utm_source` and `utm_medium`:

* `utm_source` -- `rtbhouse`
* `utm_medium` -- `cpc`

This matching can be changed inside the admin panel by specifying appropriate values for the **UTM source** and **UTM medium** options.


# Snapchat
Source: https://docs.segmentstream.com/project-configuration/data-sources/snapchat

Connect Snapchat Ads to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Snapchat">
    Choose **Snapchat** from the list.
  </Step>

  <Step title="Authenticate">
    Click **Click to connect with Snapchat** and go through the authentication and setup flow.
  </Step>

  <Step title="Select account">
    Select the account from which you would like to import the cost data.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

The Snapchat Ads API does not support extracting UTM tagging structures from ads. To ensure SegmentStream can link ad costs to session data, you will need to use [URL macro parameters](https://businesshelp.snapchat.com/s/article/add-url-macros?language=en_US) in your ad URLs.

<Steps>
  <Step title="Open URL parameters">
    In the **Ad Details** section of your ad setup, click on the **Build URL parameters** option.
  </Step>

  <Step title="Set campaign and ad IDs">
    We recommend passing the `{{campaign.id}}` value to the Campaign ID field, and `{{ad.id}}` to the Campaign content field. However, if you cannot alter the existing tags, you can skip this step and proceed to add custom parameters.
  </Step>

  <Step title="Add custom parameters">
    In the **Custom parameters** setting add `campaign_id` and `ad_id` with the values `{{campaign.id}}` and `{{ad.id}}` respectively. If you implement these custom parameters, there is no need to edit the Campaign ID and Campaign content fields.
  </Step>

  <Step title="Continue">
    Click **Continue**.
  </Step>
</Steps>

For more information on how to implement URL parameters in your ads, refer to the [Snapchat documentation](https://businesshelp.snapchat.com/s/article/add-url-macros?language=en_US).


# Snowflake
Source: https://docs.segmentstream.com/project-configuration/data-sources/snowflake

Connect Snowflake to SegmentStream and import arbitrary tables or query results into your project's BigQuery dataset.

Snowflake is a general-purpose data source — instead of pulling from an ad platform API, SegmentStream runs a SQL query you write against a Snowflake warehouse and loads the results into a BigQuery table you choose. Use this to bring CRM tables, offline conversions, product catalogues, or any other Snowflake-hosted data alongside the rest of your SegmentStream data.

## Before you begin

You will need:

* A Snowflake **user** authenticated via key-pair (not password). Follow Snowflake's [key-pair authentication guide](https://docs.snowflake.com/en/user-guide/key-pair-auth) to generate an RSA key pair and register the public key on the user with `ALTER USER <user> SET RSA_PUBLIC_KEY='...'`.
* The **private key** in PEM format (starts with `-----BEGIN PRIVATE KEY-----`). Keep it safe — you'll paste it into SegmentStream during setup.
* A Snowflake **warehouse** the user can use, and privileges to `USAGE` on the warehouse, `USAGE` on the database and schema, and `SELECT` on the tables the query touches.
* (Optional) A dedicated **role** to scope permissions.

<Tip>
  We recommend creating a service user in Snowflake specifically for
  SegmentStream, with only the privileges required for the queries you plan
  to import. Rotating credentials is easier when the account is not shared.
</Tip>

## Example Snowflake setup

If you're setting up SegmentStream access from scratch, the pattern below is
a good starting point. It creates a dedicated role and service user, wraps
the source data in a secure view so only what you deliberately expose is
readable, and grants the minimum privileges needed.

Run as `ACCOUNTADMIN`:

```sql theme={null}
-- 1. Dedicated role for SegmentStream.
CREATE OR REPLACE ROLE SEGMENTSTREAM_ROLE;

-- 2. Service user, registering the public half of your RSA key pair.
--    Paste the key body between the quotes with no BEGIN/END lines
--    and no whitespace.
CREATE OR REPLACE USER SEGMENTSTREAM_SERVICE_USER
  TYPE = SERVICE
  RSA_PUBLIC_KEY = '<PUBLIC_KEY_BODY>'
  DEFAULT_ROLE = SEGMENTSTREAM_ROLE;

-- 3. (Optional) Proxy database + secure view so SegmentStream reads only
--    what you deliberately expose. Replace SOURCE_DB.SOURCE_SCHEMA.SOURCE_TABLE
--    with the table you want to import.
CREATE OR REPLACE DATABASE SEGMENTSTREAM_PROXY_DB;
CREATE OR REPLACE SCHEMA   SEGMENTSTREAM_PROXY_DB.ACCESS;

CREATE OR REPLACE SECURE VIEW SEGMENTSTREAM_PROXY_DB.ACCESS.MY_FEED AS
SELECT * FROM SOURCE_DB.SOURCE_SCHEMA.SOURCE_TABLE;

-- 4. Grant privileges. Replace COMPUTE_WH with the warehouse
--    SegmentStream should use.
GRANT USAGE  ON WAREHOUSE COMPUTE_WH                            TO ROLE SEGMENTSTREAM_ROLE;
GRANT USAGE  ON DATABASE  SEGMENTSTREAM_PROXY_DB                TO ROLE SEGMENTSTREAM_ROLE;
GRANT USAGE  ON SCHEMA    SEGMENTSTREAM_PROXY_DB.ACCESS         TO ROLE SEGMENTSTREAM_ROLE;
GRANT SELECT ON VIEW      SEGMENTSTREAM_PROXY_DB.ACCESS.MY_FEED TO ROLE SEGMENTSTREAM_ROLE;

-- 5. Assign the role to the service user.
GRANT ROLE SEGMENTSTREAM_ROLE TO USER SEGMENTSTREAM_SERVICE_USER;
```

<Tip>
  To rotate the RSA key later, run
  `ALTER USER SEGMENTSTREAM_SERVICE_USER SET RSA_PUBLIC_KEY='<NEW_KEY_BODY>'`
  as `ACCOUNTADMIN`. Update the corresponding private key in the SegmentStream
  data source configuration afterwards.
</Tip>

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Snowflake">
    Choose **Snowflake** from the list.
  </Step>

  <Step title="Provide the private key">
    Paste the **Private Key (PEM)** into the input field. If the key is encrypted, also fill in the **Private Key Passphrase**. Click **Save**.
  </Step>

  <Step title="Configure the connection">
    Fill in the connection and query fields (see [Configuration fields](#configuration-fields) below), then click **Save**.
  </Step>

  <Step title="Activate">
    Once the source is saved, click **Activate** in the paused banner (or the toolbar) to start daily imports.
  </Step>
</Steps>

## Configuration fields

<ResponseField name="Account" type="string">
  Your Snowflake account identifier, including the region and cloud
  (e.g. `xy12345.us-east-1` or `xy12345.eu-central-1.aws`). You can find it
  in the URL you use to log in to Snowflake — everything between `https://`
  and `.snowflakecomputing.com`.
</ResponseField>

<ResponseField name="User" type="string">
  The Snowflake username the private key is registered against.
</ResponseField>

<ResponseField name="Warehouse" type="string">
  The Snowflake warehouse used to run the query. The user must have `USAGE`
  privilege on this warehouse.
</ResponseField>

<ResponseField name="Role" type="string">
  Optional. The role Snowflake assumes when running the query. Leave empty
  to use the user's default role.
</ResponseField>

<ResponseField name="Database" type="string">
  The database that contains the tables you want to query.
</ResponseField>

<ResponseField name="Schema" type="string">
  The schema inside the database. Combined with `Database`, this is the
  search path Snowflake uses for unqualified table names in your query.
</ResponseField>

<ResponseField name="SQL Query" type="string">
  The `SELECT` statement executed on every daily run. Use `{{date_from}}`
  and `{{date_to}}` placeholders to filter to the daily window — see
  [Writing the query](#writing-the-query).
</ResponseField>

<ResponseField name="Destination table name" type="string">
  Name of the BigQuery table (inside your project's SegmentStream dataset)
  that the query result is loaded into. The table is created on the first
  successful run and re-populated on every subsequent run.
</ResponseField>

<ResponseField name="Partition table by date" type="boolean">
  When enabled, the destination table is date-partitioned by the daily
  window, and each run replaces the day's partition with the query
  results. When disabled, each run replaces the entire table.
</ResponseField>

## Writing the query

SegmentStream runs your query once per day, substituting the placeholders
`{{date_from}}` and `{{date_to}}` with the daily window as `YYYY-MM-DD`
strings. Wrap the placeholders in single quotes so Snowflake interprets them
as dates:

```sql theme={null}
SELECT
  order_id,
  customer_id,
  order_total,
  order_created_at
FROM analytics.crm.orders
WHERE order_created_at >= '{{date_from}}'
  AND order_created_at <  '{{date_to}}'
```

Keep the query deterministic — the same window should always return the
same rows, otherwise late-arriving updates will not be reflected in
BigQuery unless you turn on **Partition table by date** and let re-runs
replace older partitions.

<Warning>
  The query must return columns with names and types Snowflake can serialize
  to JSON. Complex types (`OBJECT`, `ARRAY`, `VARIANT`) are supported and
  land in BigQuery as `STRING` — cast to JSON strings if you need to preserve
  nested structure downstream.
</Warning>

## Destination table

The destination table lives in the SegmentStream-managed BigQuery dataset
for your project. The schema is inferred from the query output on the first
run and enforced on subsequent runs; adding a new column to the query
requires deleting the destination table and letting SegmentStream re-create
it.

When **Partition table by date** is enabled the table has a date partition
column matching the daily window, and each run replaces the partition for
its own window only — safe for backfills and re-runs. When it's disabled
the whole table is truncated and reloaded on every run.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed / JWT signature error">
    Check that the private key you pasted matches the public key registered
    on the Snowflake user with `DESC USER <user>`. The `RSA_PUBLIC_KEY_FP`
    fingerprint on Snowflake side should match the fingerprint of the
    private key you provided.
  </Accordion>

  <Accordion title="Warehouse suspended or user has no privilege">
    The Snowflake user must have `USAGE` on the warehouse and privileges to
    read from the database, schema, and tables the query references. Run
    `SHOW GRANTS TO USER <user>` in Snowflake to audit.
  </Accordion>

  <Accordion title="Query returned zero rows">
    Confirm that `{{date_from}}` and `{{date_to}}` cover the range you
    expect — the default is a one-day window ending at your project's most
    recent active date. If you use `>= date_from AND < date_to`
    (recommended), the window excludes the upper bound; adjust filters
    accordingly.
  </Accordion>

  <Accordion title="Data source paused after re-authorization">
    Re-authorizing an existing Snowflake source (for example when you
    rotate the private key) pauses the source as a safety step. Click
    **Activate** in the paused banner on the data source configuration
    form to resume imports.
  </Accordion>
</AccordionGroup>


# StackAdapt
Source: https://docs.segmentstream.com/project-configuration/data-sources/stackadapt

Connect StackAdapt to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Generate an API token in StackAdapt">
    In StackAdapt, generate a personal API token from your account settings. The token needs read access to the advertisers whose spend you want to import.
  </Step>

  <Step title="Navigate to Data Sources">
    Inside the SegmentStream admin panel, navigate to the **Data Sources** page and click **+ NEW** in the top-right corner.
  </Step>

  <Step title="Select StackAdapt">
    Choose **StackAdapt** from the list.
  </Step>

  <Step title="Enter your API token">
    Paste the token into the **StackAdapt API token** field and continue.
  </Step>

  <Step title="Add advertiser IDs">
    In the **Advertiser IDs** field, add the numeric ID for each advertiser you want to import. Use **Add advertiser ID** to add more than one — a single data source can pull spend for multiple advertisers under the same token.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

SegmentStream reads UTM parameters directly from each ad's **click URL** in StackAdapt. Only the standard `utm_*` keys are picked up — `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, and `utm_id`. Any other query parameters on the URL are ignored by the connector.

Populate the values with StackAdapt's dynamic macros so each ad reports its own campaign, line item, and creative on click:

```plain text theme={null}
utm_source=stackadapt&utm_medium=paid&utm_campaign={SA_CAMPAIGN_NAME}&utm_content={SA_CREATIVE_ID}&utm_id={SA_CAMPAIGN_ID}
```

Add this to the **landing page URL configuration** on each campaign in StackAdapt Campaign Manager. Keep the curly braces on the macros — StackAdapt substitutes the real values at click time.

Available StackAdapt macros:

| Macro                | Substituted with  |
| -------------------- | ----------------- |
| `{SA_CAMPAIGN_NAME}` | The campaign name |
| `{SA_CAMPAIGN_ID}`   | The campaign ID   |
| `{SA_LINE_ITEM_ID}`  | The line item ID  |
| `{SA_CREATIVE_ID}`   | The creative ID   |

Once the click URLs carry `utm_source`, `utm_medium`, and `utm_campaign`, StackAdapt cost data will join to sessions in SegmentStream reports.

<Tip>
  If spend loads into your reports but campaigns don't appear alongside sessions, open a served click URL and confirm that `utm_source`, `utm_medium`, and `utm_campaign` are present and non-empty. StackAdapt's own `{SA_*}` macros only substitute after the ad is served — a preview URL in the campaign manager may still show the literal `{SA_CAMPAIGN_NAME}` text.
</Tip>


# TikTok
Source: https://docs.segmentstream.com/project-configuration/data-sources/tiktok

Connect TikTok Ads to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select TikTok">
    Choose **TikTok** from the list.
  </Step>

  <Step title="Authenticate">
    Click **To continue, authenticate with TikTok** and go through the authentication and setup flow.
  </Step>

  <Step title="Name the data source">
    Name your data source.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

Adding a `utm_id` parameter to your tagging template will guarantee improved stitching quality of costs to sessions without altering the rest of your existing UTM tags.

<Steps>
  <Step title="Open URL parameters">
    In the **Destination** section of your ad setup, click on the **Build URL parameters** option.
  </Step>

  <Step title="Add utm_id parameter">
    Click **+ Add**. Enter `utm_id` in the left input field, and `__CAMPAIGN_ID__-__AID__-__CID__` into the right input field.
  </Step>

  <Step title="Apply">
    Click **Apply**.
  </Step>
</Steps>

## Supported dynamic URL parameters

TikTok allows the use of dynamic URL tagging parameters to track campaigns.

SegmentStream supports the following parameters:

| Name                | Description                |
| ------------------- | -------------------------- |
| `__CAMPAIGN_NAME__` | Advertising campaign name. |
| `__CAMPAIGN_ID__`   | Advertising campaign ID.   |
| `__AID_NAME__`      | Ad group name.             |
| `__AID__`           | Ad group ID.               |
| `__CID_NAME__`      | Creative name.             |
| `__CID__`           | Creative ID.               |


# Twitter (X Ads)
Source: https://docs.segmentstream.com/project-configuration/data-sources/x-ads

Connect X Ads (formerly Twitter Ads) to SegmentStream and import campaign cost data.

## Getting started

<Steps>
  <Step title="Navigate to Data Sources">
    Inside the admin panel navigate to the **Data Sources** page and click **+ NEW** on the top right corner.
  </Step>

  <Step title="Select Twitter (X Ads)">
    Choose **Twitter (X Ads)** from the list.
  </Step>

  <Step title="Authenticate">
    Click **Authenticate with Twitter (X Ads)** and go through the authentication flow.
  </Step>

  <Step title="Select accounts">
    Select the accounts you would like to connect.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## UTM tagging best practices

Since X Ads do not support dynamic UTM parameters, you must manually input the campaign and ad group names as tracking parameters in the website URL of your promoted post. This manual entry is essential for SegmentStream to accurately attribute ad platform clicks to sessions on your website.

<Steps>
  <Step title="Go to Legacy Ads Manager">
    Go to your Ads Manager, and click **Go to Legacy**.
  </Step>

  <Step title="Open Ad groups tab">
    Select the **Ad groups** tab and click on **Metrics: Summary** > **Customise metrics**.
  </Step>

  <Step title="Select metrics">
    Select the **Ad Group ID** and **Campaign ID** metrics and click **Apply**.
  </Step>

  <Step title="Note the IDs">
    Find the ad group you want to track and note the **Ad Group ID** and **Campaign ID** values (for example, `47604328` and `36868108`).
  </Step>

  <Step title="Edit ad group">
    Click on the more options icon next to your ad group name and click **Edit ad group**.
  </Step>

  <Step title="Edit website URL">
    Edit the **Website URL** field for each ad within the ad group.
  </Step>

  <Step title="Add utm_id parameter">
    Add the `utm_id` parameter to the URL, combining the Campaign ID and Ad Group ID with an underscore. For example:

    ```plain text theme={null}
    https://segmentstream.com?utm_source=x&utm_medium=paid-social&utm_campaign=Offers&utm_id=36868108_47604328
    ```
  </Step>
</Steps>

Once the parameters are implemented, sessions will be linked with costs down to the ad group level, and SegmentStream reports will display the X Ads campaign name and ad group name accordingly.


# Data warehouse
Source: https://docs.segmentstream.com/project-configuration/data-warehouse

Choose between the SegmentStream-hosted data warehouse or your own Google BigQuery instance.

By default, all projects are created using the SegmentStream data warehouse, which allows for a quick and easy project setup. Enterprise plan users that want to store their data in their own Google BigQuery data warehouse can contact their project manager to enable this feature.

Read about each data warehouse option below to better understand which solution suits your business:

<CardGroup>
  <Card title="SegmentStream" icon="warehouse" href="/project-configuration/data-warehouse/segmentstream">
    Use the built-in SegmentStream data warehouse for a quick and easy project setup.
  </Card>

  <Card title="Google BigQuery" icon="database" href="/project-configuration/data-warehouse/google-bigquery">
    Use your own Google BigQuery instance for full control over data storage and access.
  </Card>
</CardGroup>

## SegmentStream data warehouse

The built-in SegmentStream data warehouse is the fastest way to get started. No additional configuration is required -- your project data is stored and processed automatically.

<Tip>
  If using your own BigQuery instance is not feasible, contact your SegmentStream manager to confirm the hosted warehouse is enabled for your project.
</Tip>

## Google BigQuery

Enterprise plan users can connect their own Google BigQuery instance for full control over data storage and access. To set this up:

1. Contact your SegmentStream project manager to enable BigQuery integration.
2. Provide the required BigQuery project ID and dataset details.
3. Grant the necessary permissions to the SegmentStream service account.

Your project manager will guide you through the specific steps for your organization.


# Google BigQuery
Source: https://docs.segmentstream.com/project-configuration/data-warehouse/google-bigquery

Use your own Google BigQuery instance as the central data warehouse for your SegmentStream project.

<Note>
  Google BigQuery is available only on [enterprise plan](https://segmentstream.com/pricing).
</Note>

## What is Google BigQuery?

[BigQuery](https://cloud.google.com/bigquery) is Google's fully managed, petabyte scale, low cost analytics data warehouse. BigQuery is NoOps -- there is no infrastructure to manage and you don't need a database administrator -- so you can focus on analysing data to find meaningful insights, use familiar SQL, and take advantage of the pay-as-you-go model.

SegmentStream allows you to use your own Google BigQuery as the central repository of data collected by the platform from one or more sources and essentially the main data warehouse where all the data will be stored.

The main benefits of using the BigQuery data warehouse solution are:

1. **Full Access** -- All data processed and collected by SegmentStream can be read, edited, and used in any analytics platform of your choice.
2. **Data Transfer Possibility** -- The data can be migrated if you plan to switch to another data warehouse in the future.

The downsides are:

1. **Complicated Initial Setup** -- You have to follow a guide in order to connect SegmentStream to your BigQuery.
2. **Cost Variation** -- The cost that occurs when SegmentStream is working on your BigQuery will have to be covered by you, as a result the monthly cost can vary depending on the amount of processed data and SegmentStream usage.

Overall, when using the BigQuery data warehouse solution you will fully own the data that SegmentStream will collect and process, with the downside that the initial setup is more complicated and the cost of running SegmentStream on your BigQuery isn't fixed.

## Enable BigQuery data warehouse

Enterprise plan users that want to store their data in their own Google BigQuery data warehouse can contact their project manager to enable this feature.

Once the feature is enabled you should see the BigQuery option appear in the Settings menu.

<img alt="BigQuery settings menu" />

## Setup guides

<CardGroup>
  <Card title="Prepare your Google Cloud Project" icon="cloud" href="/project-configuration/data-warehouse/google-bigquery/prepare-your-google-cloud-project">
    Create a GCP account, set up billing, and create a project with BigQuery API enabled.
  </Card>

  <Card title="Grant BigQuery access to SegmentStream" icon="key" href="/project-configuration/data-warehouse/google-bigquery/grant-bigquery-access-to-segmentstream">
    Grant the required IAM roles to the SegmentStream service account.
  </Card>
</CardGroup>

## Complete connection

Complete the connection by selecting your project and dataset in the BigQuery configuration form.

<img alt="BigQuery connection form" />

<Warning>
  If you intend to use GA4 or GA360 BigQuery exports for event tracking, make sure that the data location of the BigQuery dataset employed by your SegmentStream project aligns with the configuration in GA.

  <img alt="BigQuery data location warning" />
</Warning>


# Grant BigQuery access to SegmentStream
Source: https://docs.segmentstream.com/project-configuration/data-warehouse/google-bigquery/grant-bigquery-access-to-segmentstream

Grant the required IAM roles to the SegmentStream service account so it can access your BigQuery data warehouse.

We will need access to your BigQuery, which will serve as the repository for your SegmentStream project.

Below are the steps that explain how to provide the necessary project access:

<Steps>
  <Step title="Open your SegmentStream project">
    Open your SegmentStream project.
  </Step>

  <Step title="Copy the service account email">
    Navigate to **Settings** then **BigQuery**, and copy the service account email.

    <img alt="Service account email" />
  </Step>

  <Step title="Open IAM in Google Cloud Console">
    Go to the [IAM page](https://console.cloud.google.com/iam-admin/iam) in the Google Cloud Console and select the project you want to connect with SegmentStream.
  </Step>

  <Step title="Grant access">
    Click **GRANT ACCESS**.

    <img alt="Grant access button" />
  </Step>

  <Step title="Configure roles">
    Paste the service account email address into the **New principals** field. Select the [**BigQuery Data Editor** and **BigQuery User**](https://cloud.google.com/bigquery/docs/access-control#bigquery-roles) roles. Click **Save**.

    <img alt="IAM roles configuration" />
  </Step>

  <Step title="Test the connection">
    Return to your SegmentStream project and navigate to **Settings** then **BigQuery**. Check access by clicking the **TEST AND CONNECT BIGQUERY** button.

    <img alt="Test and connect BigQuery" />
  </Step>
</Steps>

You can now follow the [BigQuery guide](/project-configuration/data-warehouse/google-bigquery) to complete the connection.


# Prepare your Google Cloud Project
Source: https://docs.segmentstream.com/project-configuration/data-warehouse/google-bigquery/prepare-your-google-cloud-project

Step-by-step guide to set up your Google Cloud Platform account, billing, and project for use with SegmentStream.

Complete this step-by-step setup guide to make sure your Google BigQuery data warehouse is ready to be connected to SegmentStream.

## Before you begin

You should have an existing [Google account](https://support.google.com/accounts/answer/27441).

## 1. Create a Google Cloud Platform account

BigQuery is a part of Google Cloud Platform. To use BigQuery you need to have a Google Cloud Platform account.

<Steps>
  <Step title="Navigate to Google Cloud Platform">
    Go to the [Google Cloud Platform page](https://cloud.google.com/) and click **Get started for free**.

    <img alt="Google Cloud Platform get started" />
  </Step>

  <Step title="Log in to your Google Account">
    Log in to your Google Account.
  </Step>

  <Step title="Complete registration">
    Fill in the registration form. Provide valid payment details -- it's important, as you need an account with an active payment method to use BigQuery with SegmentStream.
  </Step>
</Steps>

## 2. Set up a billing account

To use BigQuery with SegmentStream you need an active billing account so that you'll be able to use Google Cloud Platform resources.

Free Tier Google Cloud accounts don't support some BigQuery services which are required to use SegmentStream.

### Upgrading a Free Tier account

Go to the [main page of your Google Cloud Platform](https://console.cloud.google.com/) project and click **ACTIVATE FULL ACCOUNT**.

<img alt="Activate full account" />

More information on upgrading your account can be found [here](https://cloud.google.com/free/docs/gcp-free-tier#how-to-upgrade).

### Checking billing account status

If you don't have an **ACTIVATE FULL ACCOUNT** button on the main project page, check that you have an active billing account with a valid payment method:

<Steps>
  <Step title="Go to billing">
    Go to the [Google Cloud Platform Billing page](https://console.cloud.google.com/billing).
  </Step>

  <Step title="Check billing accounts">
    Check that you have at least one billing account with active status.

    <img alt="Billing accounts" />
  </Step>

  <Step title="Link billing to project">
    Click on **MY PROJECTS**, and confirm that the billing account is linked to the project that you want to connect with SegmentStream. If it isn't linked, click the "more icon" then **Change billing** to link an active billing account.

    <img alt="Billing my projects" />
  </Step>

  <Step title="Verify account status">
    Click on the account name and follow instructions to set the status to active if it is different.

    <img alt="Billing account status" />
  </Step>

  <Step title="Validate payment info">
    Validate your payment info (1) and check that you don't have any critical (red) billing health check issues (2).

    <img alt="Billing health check" />
  </Step>
</Steps>

If you experience an issue with setting up a billing account [consult the documentation on billing accounts](https://cloud.google.com/billing/docs/how-to/manage-billing-account).

## 3. Create a Google Cloud project

<Steps>
  <Step title="Navigate to Manage resources">
    Navigate to the [Manage resources](https://console.cloud.google.com/cloud-resource-manager?walkthrough_id=resource-manager--create-project) page in the Google Cloud console.
  </Step>

  <Step title="Select organisation">
    On the **Select organisation** drop-down list at the top of the page, select the organisation resource in which you want to create a project. If you are a free trial user, skip this step, as this list does not appear.
  </Step>

  <Step title="Create the project">
    Click **Create Project**. In the **New Project** window that appears, enter a project name and select a billing account as applicable.
  </Step>

  <Step title="Set parent organisation">
    Enter the parent organisation or folder resource in the Location box. That resource will be the hierarchical parent of the new project. If No organisation is an option, you can select it to create your new project as the top level of its own resource hierarchy.
  </Step>

  <Step title="Finish creation">
    When you're finished entering new project details, click **Create**.
  </Step>
</Steps>

<Warning>
  Before continuing, please ensure that your Google Cloud project has the BigQuery API enabled by navigating to the [BigQuery API](https://console.cloud.google.com/marketplace/product/google/bigquery.googleapis.com) page and clicking "ENABLE" if it isn't already.

  <img alt="BigQuery API enable" />
</Warning>

## What's next

Grant SegmentStream access to your Google BigQuery project by following the guide: [Grant BigQuery access to SegmentStream](/project-configuration/data-warehouse/google-bigquery/grant-bigquery-access-to-segmentstream).


# SegmentStream data warehouse
Source: https://docs.segmentstream.com/project-configuration/data-warehouse/segmentstream

Use the built-in SegmentStream data warehouse for a quick and easy project setup with no additional configuration.

By default all projects are created using the SegmentStream data warehouse which allows for a quick and easy project setup.

The main benefits of using the SegmentStream data warehouse option are:

1. **Reduced Infrastructure Management** -- You don't need to worry about setting up and maintaining a data warehouse yourself.
2. **Cost-Effectiveness** -- The solution is included in the fixed subscription cost, so the costs of using SegmentStream will not vary with an increase in the amount of processed data and platform usage.

Overall, using the SegmentStream data warehouse will allow you to focus on your core operations while benefiting from a reliable and efficient data infrastructure and should suit most users that don't need advanced raw data analysis.

<Tip>
  If using your own BigQuery instance is not feasible, contact your SegmentStream manager to confirm the hosted warehouse is enabled for your project.
</Tip>


# Events tracking
Source: https://docs.segmentstream.com/project-configuration/events-tracking

Configure event tracking on your website or app to feed ML models and power SegmentStream attribution.

Events are specific actions or interactions that users perform on your website or application, such as clicking a button, viewing a page, or completing a form. They play a significant role in training the SegmentStream machine learning models, which analyse the sequence of events leading up to conversions to power the attribution models available in reports.

## Tracking options

<CardGroup>
  <Card title="GA4 BigQuery Export" icon="google" href="/project-configuration/events-tracking/ga4-bigquery-export">
    The recommended approach for websites with Google Analytics 4 already implemented.
  </Card>

  <Card title="Adobe Analytics" icon="chart-mixed" href="/project-configuration/events-tracking/adobe-analytics">
    Connect event data from Adobe Analytics.
  </Card>

  <Card title="Consent mode" icon="shield-check" href="/project-configuration/events-tracking/consent-mode">
    Understand how SegmentStream handles user consent and privacy.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/project-configuration/events-tracking/faq">
    Frequently asked questions about event tracking.
  </Card>
</CardGroup>

## GA4 BigQuery Export

If Google Analytics 4 is already implemented on your website or app, integrating event tracking through the native GA4 BigQuery Link feature is the most straightforward approach. This method exports your GA4 event data directly to BigQuery, where SegmentStream can process it.

## Adobe Analytics

For websites using Adobe Analytics, SegmentStream can ingest event data through a dedicated integration. Contact your project manager for setup details.

## Consent mode

SegmentStream supports Google Consent Mode, allowing you to collect event data while respecting user privacy preferences. When consent is denied, SegmentStream can still attribute conversions using aggregated and modelled data.


# Adobe Analytics
Source: https://docs.segmentstream.com/project-configuration/events-tracking/adobe-analytics

Set up event tracking in SegmentStream using data from Adobe Analytics via Data Feeds.

To set up event tracking using data from Adobe Analytics, you must export raw data via its built-in Data Feeds feature.

You can find additional information about Data Feeds on the [Adobe Analytics website](https://experienceleague.adobe.com/en/docs/analytics/export/analytics-data-feed/create-feed).

## Getting started

Check if you already have an active Data Feed in Adobe Analytics by following these steps:

1. Log in to [experiencecloud.adobe.com](https://experiencecloud.adobe.com/) using your Adobe ID credentials.
2. Select the 9-square icon in the upper-right, then select **Analytics**.
3. In the top navigation bar, go to **Admin** > **Data feeds**.
4. Select Report Suite in the list.
5. See if there is an active data feed on the right side.
6. Open the data feed and check the date and time of the last data feed update to ensure that the feed has been updated recently.

## Connecting with existing Data Feed

Ideally, a data feed should be created specifically for SegmentStream integration. However, if you already have an active data feed, you cannot create another one with the same fields due to restrictions in Adobe Analytics.

If you already have a Data Feed, contact your SegmentStream manager and prepare answers to the following questions:

1. What is the data feed destination (Amazon S3, Google Cloud, Azure, FTP)?
2. Is the data feed configured to export all available columns?
3. Can you grant SegmentStream read access to the destination?
4. Can you share a small sample of data with SegmentStream (e.g. 1 full day)?

## Creating a new Data Feed

If you do not have a data feed, you need to create one with the **Google Cloud Platform** destination, as described in this [documentation](https://experienceleague.adobe.com/docs/analytics/export/analytics-data-feed/create-feed.html?lang=en).

<Warning>
  Ensure that the destination is **Google Cloud Platform** and **all columns** are selected.
</Warning>

<Tip>
  If you do not have a Google Cloud project, refer to the [Google BigQuery](/project-configuration/data-warehouse/google-bigquery) documentation on how to create one.
</Tip>

## Grant access to data feed

After creating the data feed, grant permission to SegmentStream to access the data by following these steps:

1. **Navigate to Cloud Storage**: Log in to your Google Cloud Console, navigate to "Storage", and then to "Browser".
2. **Select your bucket**: Find the bucket that you want to give access to and click on its name.
3. **Open Permissions tab**: Once inside the bucket, find the "Permissions" tab near the top of the page.
4. **Add member**: Click on the "Add" button to add a new member.
5. **Configure permission**:
   * **New Member**: Enter the email address `bigquery@segmentstream.com`.
   * **Role**: Select the role as **Storage Object Viewer** to give read-only access to the bucket.
6. **Save**: Click "Save" to apply the changes.


# Consent mode
Source: https://docs.segmentstream.com/project-configuration/events-tracking/consent-mode

Understand how SegmentStream handles user consent and privacy when collecting behavioural data.

SegmentStream prioritizes the privacy of your users and ensures transparency in how behavioural data is handled within the application.

## Consent-driven model

SegmentStream strictly adheres to a consent-driven model, collecting behavioural data only when users explicitly consent through the implemented consent management solution on your website or app.

## Implementing consent mode

Consent implementation differs depending on the event tracking method used to integrate SegmentStream. For more information on event tracking, refer to the [Events tracking](/project-configuration/events-tracking) documentation.

### Streaming

When using event tracking through a streaming connection, data is sent directly to SegmentStream servers. If users give consent, their choices align with Google Analytics 4 for consistent and compliant data collection. This means that if consent mode is set up in the Google Analytics 4 tag forwarding data to SegmentStream, it will be processed accordingly.

### Google Analytics 4 BigQuery Link

When events tracking uses the BigQuery Link, SegmentStream accesses data that has already been processed according to the consent mode set up for the connected Google Analytics 4 stream. It is recommended to review your GA4 consent mode implementation before connecting SegmentStream.

### Adobe Analytics

When event tracking is implemented through Adobe Analytics, SegmentStream only accesses data that has been collected in accordance with the rule conditions set in the Adobe customer consent implementation. It is recommended to review your Adobe Analytics consent mode implementation before connecting SegmentStream.

## Consent and attribution behaviour

When users reject analytics (statistics) cookies, their session data is anonymised and remains non-identifiable. However, even in its anonymised form, this data helps improve SegmentStream's machine learning models, leading to more accurate predictions.

* If your website's GA4 consent mode allows anonymised data to be sent when consent is rejected, SegmentStream's attribution model distributes the conversions from unconsented visits as a score across sessions where consent was granted.
* If GA4 tracking is completely disabled when consent is rejected, SegmentStream only distributes conversions among consented visits.

The following diagram shows an example of conversions tracked on visits where consent was rejected being distributed to visits that accepted consent.

<img alt="Consent mode attribution behaviour" />


# FAQ
Source: https://docs.segmentstream.com/project-configuration/events-tracking/faq

Frequently asked questions about event tracking in SegmentStream.

### Can historical data be retrieved from Google Analytics or other similar platforms?

SegmentStream only begins data collection once the SegmentStream tracker has been installed on your website. It does not pull data from before that point. Furthermore, to build the first machine learning model for ML-based attribution, it requires at least three weeks of data following the installation.

### How can I send data to SegmentStream if my GA4 is already sending data to a custom endpoint?

You have to send events to SegmentStream through a separate GA4 configuration as described in the [SegmentStream SDK](/project-configuration/sdk) guides.

### How can I accurately track 'Quick Purchase' (e.g., PayPal Express, Apple Pay) without altering the original traffic source for correct attribution?

To maintain accurate attribution, configure a referral exclusion list within SegmentStream's Events tracking settings. This ensures referrals from payment system pages are ignored.

### Is it necessary to have Google Analytics tracking set up to use SegmentStream?

SegmentStream operates using the same data protocol as GA4. To begin data collection, you must implement tracking on your website in the GA4 format. However, it is not mandatory to send data to GA4 servers; you can configure it so that only SegmentStream captures behavioural data. Depending on your preferences, you can:

1. Allow both SegmentStream and GA4 to collect data in the GA4 format.
2. Permit only SegmentStream to gather data using the GA4 format.

### How can I track subdomain referrals?

SegmentStream usually sees a visit as coming from a different website only when someone clicks a link from a completely different domain. For example, if SegmentStream is tracking events on `shop.site.com` and someone clicks a link from `other.site.com` to `shop.site.com`, it is typically counted as a direct visit. However, if they click from `other.site.co.uk` to `shop.site.com`, it is seen as a referral.

You can set up SegmentStream to consider visits from related subdomains as referrals too. For instance, going from `other.site.com` to `shop.site.com` could be counted as a referral.

If you want to enable this feature, reach out to the support team for help setting it up.

### Why are the number of users and sessions different in GA4 and SegmentStream reports?

The discrepancies between GA4 and SegmentStream user and session counts can arise due to several reasons:

1. **GA4 Modelling:** By default, GA4 uses machine learning to estimate metrics for users and sessions who haven't given consent for analytics cookies. In contrast, SegmentStream shows user and session metrics based on users who have given consent and uses machine learning only for metrics related to conversions. To see the real number of tracked users and sessions in your GA4 reports, switch your "Reporting identity" to the "Observed" setting. For more details on GA4 modelling, visit this [link](https://support.google.com/analytics/answer/11161109).
2. **Filters in GA4**: Your GA4 property might have filters applied, such as those filtering out internal traffic. For a detailed understanding, visit this [link](https://support.google.com/analytics/answer/13296761?hl=en).
3. **Session definitions**: GA4 and SegmentStream use different logic to define a session. In GA4, once a session initiates, it continues until there is a 30-minute gap between events. In contrast, SegmentStream can initiate a new session with a click to a paid channel with UTM parameters.
4. **Timezone discrepancies**: Your GA4 property and SegmentStream project might be set to different time zones.

To get a more consistent view, it is advisable to focus on the "users" metric. Should you notice a difference greater than 1%, contact support via the support form in your admin panel.


# GA4 BigQuery Export
Source: https://docs.segmentstream.com/project-configuration/events-tracking/ga4-bigquery-export

Set up Google Analytics 4 BigQuery Export to send event data to SegmentStream for attribution and ML-powered insights.

To use event data from Google Analytics 4 in SegmentStream, you need to first set up a Google Analytics 4 BigQuery Link. Refer to the [Set up GA4 BigQuery Link](/project-configuration/events-tracking/ga4-bigquery-export/set-up-ga4-bigquery-link) guide and ensure the following requirements are met:

* The data location of the BigQuery dataset used in SegmentStream matches the one configured in GA4.

  <img alt="GA4 BigQuery data location setting" />

* Both the **Daily** and **Streaming** export types are enabled.

  <img alt="GA4 BigQuery streaming export setting" />

* No events are excluded in your BigQuery Link settings.

  <img alt="GA4 BigQuery no excluded events" />

Once the GA4 BigQuery Export is set up, data should start flowing to your BigQuery project within 24 hours. After that happens, you can connect your Google Analytics 4 to SegmentStream.

## Connecting Google Analytics 4 to SegmentStream

<Steps>
  <Step title="Navigate to events tracking">
    Inside the admin panel navigate to **Settings** > **Events Tracking**.
  </Step>

  <Step title="Add Google Analytics 4">
    Click **+ ADD** and select the **Google Analytics 4** option.
  </Step>

  <Step title="Authorise your Google account">
    In the drawer that opens, authorise your Google account.
  </Step>

  <Step title="Select account and property">
    Select the account and property where your data is collected.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>

  <Step title="Wait for data processing">
    All event data exported to your BigQuery in the past 60 days will be processed by SegmentStream, and reports will become available. This process might take a couple of hours.
  </Step>
</Steps>

<Info>
  Follow the guide on [Additional GA4 settings](/project-configuration/events-tracking/ga4-bigquery-export/additional-ga4-settings) to pass additional parameters that help SegmentStream integrate better with your business.
</Info>

<img alt="GA4 connection in SegmentStream" />

## Referral exclusion logic

To ensure SegmentStream provides accurate insights, it must correctly identify where each session's traffic is coming from. Properly setting up referral exclusions is key, especially when users move between different domains or subdomains during redirects.

Typical scenarios for using referral exclusions include stopping traffic from payment gateways, login systems, or other internal processes from being counted as external referrals.

SegmentStream uses the settings from your Google Analytics 4 (GA4) property to filter out unwanted referrals. If your GA4 is correctly set up, SegmentStream automatically applies those same settings. This process helps identify and exclude unwanted referral traffic through the following methods:

* Identifying when visitors navigate within different parts of your site or its subdomains, preventing these movements from being counted as external visits.
* Redirects between websites specified in your GA4 stream's cross-domain measurement function are treated similarly to redirects within the same domain and are excluded from referral tracking. Learn more about [setting up cross-domain measurement](https://support.google.com/analytics/answer/10071811?hl=en) in Google's documentation.
* You can further control unwanted referrals by configuring the unwanted referrals list in your GA4 stream settings. Refer to Google's documentation for [configuring unwanted referrals](https://support.google.com/analytics/answer/10327750?hl=en).

## BigQuery access issues

If the Google Analytics 4 BigQuery link is connected to a different project than the one specified in the SegmentStream BigQuery settings, you need to provide additional permissions before connecting event tracking.

### Get your service account email

1. In your SegmentStream project, navigate to **Settings** > **Events Tracking**.
2. Click on the Google Analytics 4 option.
3. Select the account and property where your data is collected.
4. Copy the service account email from the Google Analytics 4 connection settings.

<img alt="Service account email in SegmentStream" />

### Find the BigQuery project linked to GA4

1. In your [Google Analytics](https://analytics.google.com/) property, go to **Admin**.
2. Under Product Links, click **BigQuery Links**.
3. You will see the ID and name of the linked project.

<img alt="GA4 BigQuery linked project" />

### Set permissions in your Google Cloud account

<Steps>
  <Step title="Open IAM in Google Cloud Console">
    Go to the [IAM page](https://console.cloud.google.com/iam-admin/iam) in the Google Cloud Console.
  </Step>

  <Step title="Select the linked project">
    Click on the project selection menu in the navigation bar, and select the project linked to Google Analytics 4.

    <img alt="Google Cloud project selector" />
  </Step>

  <Step title="Grant access">
    Click **GRANT ACCESS**.

    <img alt="Google Cloud grant access button" />
  </Step>

  <Step title="Configure roles">
    1. Paste the service account email address into the **New principals** field.
    2. Select the [**BigQuery Data Viewer** and **BigQuery User**](https://cloud.google.com/bigquery/docs/access-control#bigquery-roles) roles.
    3. Click **Save**.

       <img alt="BigQuery roles configuration" />
  </Step>
</Steps>

### Test connection and save

1. Return to your SegmentStream project and navigate to the Google Analytics 4 connection.
2. Click **TEST CONNECTION**.
3. If the permissions have been correctly set up, the **SAVE** button should be active. Click it to complete your Google Analytics 4 tracking setup.

<img alt="GA4 test connection in SegmentStream" />

## In this section

<CardGroup>
  <Card title="Set up GA4 BigQuery Link" icon="link" href="/project-configuration/events-tracking/ga4-bigquery-export/set-up-ga4-bigquery-link">
    Step-by-step guide to linking your GA4 property to BigQuery.
  </Card>

  <Card title="Additional GA4 settings" icon="gear" href="/project-configuration/events-tracking/ga4-bigquery-export/additional-ga4-settings">
    Configure custom user properties and event parameters for better integration.
  </Card>
</CardGroup>


# Additional GA4 settings
Source: https://docs.segmentstream.com/project-configuration/events-tracking/ga4-bigquery-export/additional-ga4-settings

Configure custom user properties and event parameters in GA4 to improve SegmentStream integration with your business.

This guide provides step-by-step instructions for implementing custom user properties and event parameters in your Google Analytics 4 (GA4) property.

## Overview

Each section below describes the implementation for one specific property or parameter:

1. Ever Paid (`ever_paid`)
2. Is Bot (`is_bot`)
3. Customer Type (`customer_type`)

All examples include Google Tag Manager (GTM) and gtag.js approaches.

## Ever Paid (user property)

Tracks whether a user has ever made a payment or conversion on your platform. Useful for differentiating actions of paying vs. non-paying users, especially for freemium or subscription-based businesses.

### Expected values

* `true` -- The user has made at least one payment.
* `false` -- The user has never paid.

### Implementation via Google Tag Manager

<Steps>
  <Step title="Create a Data Layer Variable">
    Create a **Data Layer Variable** for `ever_paid`.
  </Step>

  <Step title="Create a GTM Variable">
    Create a Variable inside GTM that reads that value from the dataLayer, name it `ever_paid`.

    <img alt="GTM ever_paid variable" />
  </Step>

  <Step title="Create a GA4 Event Settings Variable">
    If you don't already have one, create a **GA4 Event Settings Variable**.
  </Step>

  <Step title="Add the user property">
    Under the **User Properties** section, add:

    * **Property Name:** `ever_paid`
    * **Value:** Your Data Layer variable (e.g., `{{ever_paid}}`)

      <img alt="GTM ever_paid event settings" />
  </Step>

  <Step title="Apply to GA4 tags">
    Select this Event Settings Variable in all GA4 configuration and event tags.
  </Step>
</Steps>

### Implementation via gtag.js

```javascript theme={null}
gtag('config', 'GA_MEASUREMENT_ID', {
  'user_properties': {
    'ever_paid': true // or false
  }
});
```

### Create custom dimension in GA4

<Steps>
  <Step title="Navigate to custom definitions">
    Go to **Admin** > **Data display** > **Custom definitions**.
  </Step>

  <Step title="Create custom dimension">
    Click **Create custom dimension** and set:

    * **Scope:** User
    * **Dimension name:** ever\_paid
    * **Description:** Indicates if the user has ever paid
    * **User property:** `ever_paid`

      <img alt="GA4 custom dimension for ever_paid" />
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## Is Bot (user property)

Flags users identified as bots or automated sessions. This allows filtering out bot traffic.

### Expected values

* `true` -- The session/user is identified as a bot.
* `false` -- The user is human.

### Implementation via Google Tag Manager

<Steps>
  <Step title="Create a Data Layer Variable">
    Create a **Data Layer Variable** for `is_bot`.
  </Step>

  <Step title="Create a GTM Variable">
    Create a Variable inside GTM that reads that value from the dataLayer, name it `is_bot`.

    <img alt="GTM is_bot variable" />
  </Step>

  <Step title="Create a GA4 Event Settings Variable">
    If you don't already have one, create a **GA4 Event Settings Variable**.
  </Step>

  <Step title="Add the user property">
    Under the **User Properties** section, add:

    * **Property Name:** `is_bot`
    * **Value:** Your Data Layer variable (e.g., `{{is_bot}}`)

      <img alt="GTM is_bot event settings" />
  </Step>

  <Step title="Apply to GA4 tags">
    Select this Event Settings Variable in all GA4 configuration and event tags.
  </Step>
</Steps>

### Implementation via gtag.js

```javascript theme={null}
gtag('config', 'GA_MEASUREMENT_ID', {
  'user_properties': {
    'is_bot': true // or false
  }
});
```

### Create custom dimension in GA4

<Steps>
  <Step title="Navigate to custom definitions">
    Go to **Admin** > **Data display** > **Custom definitions**.
  </Step>

  <Step title="Create custom dimension">
    Click **Create custom dimension** and set:

    * **Scope:** User
    * **Dimension name:** is\_bot
    * **Description:** Indicates if the user is identified as a bot
    * **User property:** `is_bot`

      <img alt="GA4 custom dimension for is_bot" />
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

## Customer Type (event parameter)

Tracks whether a conversion event comes from a new or returning customer. Helps measure acquisition vs. retention performance.

### Expected values

* `new` -- The customer is making their first purchase.
* `returning` -- The customer has purchased before.

### Implementation via Google Tag Manager

<Steps>
  <Step title="Create a Data Layer Variable">
    Add a **Data Layer Variable** for `customer_type` to the conversion dataLayer event when a user completes a transaction.
  </Step>

  <Step title="Create a GTM Variable">
    Create a Variable inside GTM that reads that value from the dataLayer, name it `customer_type`.

    <img alt="GTM customer_type variable" />
  </Step>

  <Step title="Add event parameter to GA4 tag">
    Open your GA4 tag that tracks the conversion. Under the **Event Parameters** section, add:

    * **Property Name:** `customer_type`
    * **Value:** Your Data Layer variable (e.g., `{{customer_type}}`)

      <img alt="GTM customer_type event parameter" />
  </Step>
</Steps>

### Implementation via gtag.js

Example adding `customer_type` to the purchase event:

```javascript theme={null}
gtag('event', 'purchase', {
  transaction_id: 'T12345',
  value: 199.99,
  currency: 'USD',
  // Custom parameter: Customer Type
  customer_type: 'new' // "new" or "returning"
});
```


# Set up GA4 BigQuery Link
Source: https://docs.segmentstream.com/project-configuration/events-tracking/ga4-bigquery-export/set-up-ga4-bigquery-link

Link your Google Analytics 4 property to BigQuery to export event data for use with SegmentStream.

To use event data from Google Analytics 4 in SegmentStream, you must first set up a Google Analytics 4 BigQuery Link. This guide outlines the necessary steps.

## Getting started

Ensure your Google BigQuery project is ready and billing is set up by following the [Google BigQuery](/project-configuration/data-warehouse/google-bigquery) guide.

## Link a Google Analytics 4 property to BigQuery

This process must be completed by a user with **Owner** access to the Google Cloud project. The Owner role is assigned to the user who created the project, but you can also grant this permission through the [Google Cloud Project IAM](https://console.cloud.google.com/iam-admin/iam) page.

<Steps>
  <Step title="Select your GA4 property">
    Go to [Google Analytics 4](https://analytics.google.com/) and select the property where your data is collected.
  </Step>

  <Step title="Open Admin settings">
    Click on the **Admin** button.
  </Step>

  <Step title="Navigate to BigQuery links">
    In the **Product Links** section, click **BigQuery links**.

    <img alt="GA4 BigQuery links page" />
  </Step>

  <Step title="Configure the BigQuery link">
    1. Click **Link** > **Choose a BigQuery project**.

    2. Select the BigQuery project you created.

    3. Select the **Data location** that matches your business's region.

    4. Enable both the **Daily** and **Streaming** export types.

       <img alt="GA4 BigQuery streaming export setting" />

    5. Click **Submit**.

       <img alt="GA4 BigQuery link setup" />
  </Step>
</Steps>

## Next step

Once the GA4 BigQuery Export is set up, data should start flowing to your BigQuery project within 24 hours. After this, you can proceed to connect your Google Analytics 4 to SegmentStream by following the [GA4 BigQuery Export](/project-configuration/events-tracking/ga4-bigquery-export) guide.


# Identity graph
Source: https://docs.segmentstream.com/project-configuration/identity-graph

Connect fragmented user sessions across browsers, devices, and channels for accurate multi-touch attribution.

The SegmentStream Identity Graph is a core part of the attribution infrastructure. It connects fragmented user sessions across browsers, devices, and channels to enable more accurate multi-touch attribution (MTA) and a unified view of the customer journey.

By using a combination of identifiers collected on-site, the identity graph helps associate sessions with users across devices -- even when they don't log in -- improving attribution, optimisation, and decision-making.

## Why it matters

Modern users interact with brands across multiple channels and devices. A typical journey may include:

* Subscribing to a newsletter on mobile
* Clicking a retargeting ad on desktop
* Converting later on tablet

Without stitching these sessions together, each would be seen as a separate user, breaking attribution.

The identity graph enables SegmentStream to connect these interactions, reconstruct the full path to conversion, and attribute value accurately.

## What data is used to stitch sessions

SegmentStream combines the following identifiers to build and enrich the identity graph:

| Identifier           | Description                                                                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_id`            | A persistent user identifier (e.g. when logged in) -- the strongest signal.                                                                                            |
| `ip_address`         | Used as a fallback when stronger IDs are missing; often combined with timestamp and location heuristics.                                                               |
| `click_id`           | Unique ad click identifiers (e.g. `gclid`, `fbclid`) used to match sessions to ad interactions.                                                                        |
| `email hash (ehash)` | A SHA-256 hashed version of the user's email collected on forms (e.g. newsletter signup, checkout). Enables matching to email campaigns and cross-device interactions. |

<Note>
  SegmentStream uses confidence-weighted merging logic to stitch sessions based on multiple identifiers.
</Note>

## Use cases

* **Cross-device attribution** -- Match a subscription on mobile to a purchase on desktop via `ehash`.
* **Campaign path stitching** -- Connect Meta, Google, and direct sessions leading to a conversion.
* **Better ML input** -- Feed complete user journeys into conversion modelling, improving performance.

## Best practices for implementation

To get the most from the identity graph, implement the following:

* **Send `user_id` to GA4** whenever a user logs in or authenticates.
* **Preserve `click_id` parameters** when redirecting from ad platforms by implementing the [SegmentStream SDK](/project-configuration/sdk).
* **Implement `ehash`** by capturing and hashing emails from forms (e.g. newsletter, checkout) and adding `ehash` to email links (e.g. `https://site.com?ehash=...`). SegmentStream automatically captures `ehash` from URLs -- you only need to ensure it's included in your email links and sent with on-site form events.

## In this section

<CardGroup>
  <Card title="User ID" icon="user" href="/project-configuration/identity-graph/user-id">
    Implement user ID tracking in Google Analytics for cross-device attribution.
  </Card>

  <Card title="Email hash (Segment)" icon="envelope" href="/project-configuration/identity-graph/cross-device-tracking-via-email-hash-(segment)">
    Implement ehash-based cross-device tracking using Segment.
  </Card>

  <Card title="Email hash (GTM)" icon="tag" href="/project-configuration/identity-graph/cross-device-tracking-via-email-hash-(gtm)">
    Implement ehash-based cross-device tracking using Google Tag Manager.
  </Card>
</CardGroup>


# Cross-device tracking via email hash (GTM)
Source: https://docs.segmentstream.com/project-configuration/identity-graph/cross-device-tracking-via-email-hash-(gtm)

Implement ehash-based cross-device tracking using Google Tag Manager to enable session stitching in GA4 for SegmentStream attribution.

This guide explains how to implement `ehash` -- a hashed version of a user's email address -- as a user identifier to enable cross-device tracking and session stitching in GA4.

By hashing email addresses collected on-site and sending them as an event parameter (`ehash`) to GA4, you can help SegmentStream's identity graph more accurately associate sessions and users across devices and channels.

To support this:

* All links in marketing emails should include the `ehash` parameter in the URL.
* All email addresses captured onsite (e.g., during checkout or signup) must be hashed client-side and sent to GA4 as event parameters.

<Tip>
  You don't need to implement every step at once -- each part of the setup provides value on its own. For example, capturing ehash from forms now allows you to start tracking, and adding the parameter to email links can be done later.
</Tip>

This guide outlines all the steps required to fully enable `ehash` based cross-device tracking.

***

## Add `ehash` to email links

When a user submits their email on your site:

* Generate a hash (e.g., using `SHA-256`).
* Store it in your backend.
* Include the hashed email as a query parameter in all email links:

```
https://www.example.com/landing-page?ehash=hashedemail123
```

<Tip>
  This allows you to recognise and associate users on different devices when they click through from an email.
</Tip>

<Note>
  When a user lands on your site with an `ehash` parameter in the URL, SegmentStream automatically captures it -- no additional GTM or GA4 configuration is needed for this step.
</Note>

***

## Capture and hash emails from on-site forms

When a user submits an email (e.g., through a popup or signup form), send an event to GA4 along with the ehash event parameter by following these steps:

<Steps>
  <Step title="Push ehash to the dataLayer">
    Ask your developers to push an event into the `dataLayer` that includes the `ehash` value whenever a form with an email is submitted, or add the `ehash` parameter to existing dataLayer events that are already sent on form submission, for example:

    ```javascript theme={null}
    dataLayer.push({
      event: "email_form_submitted",
      ehash: "<user email hashed using the method as in the email links>"
    });
    ```
  </Step>

  <Step title="Create a Data Layer Variable for ehash">
    Inside your GTM, create a Data Layer Variable for `ehash`:

    1. Go to **Variables** then **New**
    2. Name: `DLV - ehash`
    3. Type: **Data Layer Variable**
    4. Data Layer Variable Name: `ehash`

       <img alt="DLV ehash variable" />
  </Step>

  <Step title="Create a trigger (if needed)">
    If the dataLayer event is already tracked, skip this step. Otherwise, create a GTM Trigger for the event (in this example, `email_form_submitted`):

    1. Go to **Triggers** then **New**
    2. Name: `Trigger - email_form_submitted`
    3. Trigger Type: **Custom Event**
    4. Event name: `email_form_submitted`
  </Step>

  <Step title="Create a GA4 tag (if needed)">
    If the event is already tracked in GA4, skip this step. Otherwise, create a GA4 tag to send the event:

    1. Go to **Tags** then **New**
    2. Name: `GA4 - email_form_submitted`
    3. Tag Type: **Google Analytics: GA4 Event**
    4. Configuration Tag: Select your existing GA4 config tag
    5. Event Name: `email_form_submitted`
    6. Triggering: `Trigger - email_form_submitted`
  </Step>

  <Step title="Add ehash event parameter">
    In the event that is tracking the form submission, edit the Event Parameters to add:

    * Name: `ehash`
    * Value: `{{DLV - ehash}}`

      <img alt="GA4 email form tag with ehash" />

    Save and publish the container.
  </Step>
</Steps>

<Tip>
  This ensures the `ehash` parameter is sent to GA4 when a user subscribes to the newsletter. SegmentStream can then automatically match the user if they later click a newsletter link containing the same `ehash`, linking it back to the original subscription device.
</Tip>

***

## Capture and hash email on checkout

Send an event to GA4 along with the ehash event parameter with the purchase event by following these steps:

<Steps>
  <Step title="Include ehash in the purchase dataLayer event">
    Ask your developers to include the `ehash` parameter in the `purchase` event pushed to the `dataLayer` when a transaction is completed and the user's email is available.

    ```javascript theme={null}
    dataLayer.push({
      event: "purchase",
      ehash: "<user email hashed using the method as in the email links>",
      ecommerce: {
        transaction_id: "T12345",
        value: 59.99,
        currency: "USD",
        items: [
          {
            item_id: "SKU_123",
            item_name: "Wireless Mouse",
            price: 29.99,
            quantity: 2
          }
        ]
      }
    });
    ```
  </Step>

  <Step title="Create a Data Layer Variable for ehash">
    Inside your GTM create a Data Layer Variable for `ehash` (if not already created):

    1. Go to **Variables** then **New**
    2. Name: `DLV - ehash`
    3. Type: **Data Layer Variable**
    4. Data Layer Variable Name: `ehash`

       <img alt="DLV ehash variable" />
  </Step>

  <Step title="Add ehash to the purchase GA4 tag">
    Open the GA4 Tag that is tracking the `purchase` event and edit the Event Parameters to add:

    * Name: `ehash`
    * Value: `{{DLV - ehash}}`

      <img alt="GA4 purchase tag with ehash" />

    Save and publish the container.
  </Step>
</Steps>

<Tip>
  By capturing and hashing the email at both the subscription and checkout stages, SegmentStream can reconstruct the full user journey and attribute value accurately to each marketing interaction the user had before converting.
</Tip>


# Cross-device tracking via email hash (Segment)
Source: https://docs.segmentstream.com/project-configuration/identity-graph/cross-device-tracking-via-email-hash-(segment)

Implement ehash-based cross-device tracking using Segment to enable session stitching in GA4 for SegmentStream attribution.

This guide explains how to implement `ehash` -- a hashed version of a user's email address -- as a user identifier to enable cross-device tracking and session stitching in GA4.

By hashing email addresses collected on-site and sending them as an event parameter (`ehash`) to GA4, you can help SegmentStream's identity graph more accurately associate sessions and users across devices and channels.

To support this:

* All links in marketing emails should include the `ehash` parameter in the URL.
* All email addresses captured onsite (e.g., during checkout or signup) must be hashed client-side and sent to GA4 as event parameters.

<Tip>
  You don't need to implement every step at once -- each part of the setup provides value on its own. For example, capturing ehash from forms now allows you to start tracking, and adding the parameter to email links can be done later.
</Tip>

This guide outlines all the steps required to fully enable `ehash` based cross-device tracking.

***

## Add `ehash` to email links

When a user submits their email on your site:

* Generate a hash (e.g., using `SHA-256`).
* Store it in your backend.
* Include the hashed email as a query parameter in all email links:

```
https://www.example.com/landing-page?ehash=hashedemail123
```

<Tip>
  This allows you to recognise and associate users on different devices when they click through from an email.
</Tip>

<Note>
  When a user lands on your site with an `ehash` parameter in the URL, SegmentStream automatically captures it -- no additional Segment or GA4 configuration is needed for this step.
</Note>

***

## Capture and hash emails from on-site forms

When a user submits an email (e.g., through a popup or signup form), send an event to GA4 along with the ehash event parameter by following these steps:

1. **Hash the email** when a user submits a form.
2. Send a Segment `track()` call including the `ehash`.

**Example:**

```javascript theme={null}
analytics.track("Email Form Submitted", {
  ehash: "<sha256 hashed email>",
  form_id: "newsletter_popup"
});
```

### Forwarding `ehash` to GA4 (Segment Destination settings)

The GA4 Destination in Segment forwards all event properties by default. So as long as your `track()` call includes the property below, GA4 will receive this as an event parameter:

```json theme={null}
{
  "ehash": "123hashed"
}
```

<Tip>
  This ensures the `ehash` parameter is sent to GA4 when a user subscribes to the newsletter. SegmentStream can then automatically match the user if they later click a newsletter link containing the same `ehash`, linking it back to the original subscription device.
</Tip>

***

## Capture and hash email on checkout

When the purchase is completed and the customer email is available:

1. Hash the email.
2. Include it in the Segment `Purchase` event (or whatever your ecommerce library sends).

### Example using Segment's ecommerce spec:

```javascript theme={null}
analytics.track("Order Completed", {
  order_id: "T12345",
  total: 59.99,
  currency: "USD",
  products: [
    {
      product_id: "SKU_123",
      name: "Wireless Mouse",
      price: 29.99,
      quantity: 2
    }
  ],
  ehash: "<sha256 hashed email>"
});
```

Segment's GA4 destination will forward `ehash` automatically.

<Tip>
  By capturing and hashing the email at both the subscription and checkout stages, SegmentStream can reconstruct the full user journey and attribute value accurately to each marketing interaction the user had before converting.
</Tip>


# User ID
Source: https://docs.segmentstream.com/project-configuration/identity-graph/user-id

Implement user ID tracking in Google Analytics to improve cross-device attribution in SegmentStream.

To improve cross-device attribution, it's necessary to implement the tracking of the user ID in Google Analytics.

## For GA4 via Tag Manager

<Steps>
  <Step title="Pass the parameter to dataLayer">
    On every page load after login, pass the relevant parameter `user_id` to your `dataLayer`.
  </Step>

  <Step title="Create a GTM variable">
    Create a Variable inside GTM that reads that value from the dataLayer.

    <img alt="GTM user_id dataLayer variable" />
  </Step>

  <Step title="Send the property to GA4">
    Under the Configuration Parameter section of your GA4 Google Tag, add a new row with the **user\_id** property and the corresponding **Value** (the Data Layer variable you created in step 2).

    <img alt="GTM user_id config parameter" />
  </Step>
</Steps>

## For GA4 using gtag.js

Pass a unique user ID after login to track users across sessions on different devices using the `user_id` config parameter.

```javascript theme={null}
gtag('config', 'STREAM_ID', {
  'user_id': 'USER_ID'
});
```


# Lead gen business integration
Source: https://docs.segmentstream.com/project-configuration/lead-gen

Ensure accurate attribution and data quality for businesses collecting leads through websites and ad platforms.

This section covers how to ensure accurate attribution and data quality for businesses collecting leads through websites and ad platforms.

## What you will learn

<CardGroup>
  <Card title="Website lead data" icon="paper-plane" href="/project-configuration/lead-gen-business-integration/sending-website-lead-data-to-your-crm">
    Capture and send the SegmentStream user identifier to your CRM together with lead data for consistent attribution.
  </Card>

  <Card title="Ad platform lead forms" icon="rectangle-ad" href="/project-configuration/lead-gen-business-integration/how-to-track-ad-platform-lead-forms-in-analytics-and-crm">
    Handle leads generated on ad platforms (Meta, LinkedIn, Google Ads, TikTok, etc.) by creating synthetic sessions for attribution.
  </Card>

  <Card title="Lead scoring" icon="ranking-star">
    Use ML models to score leads by quality and potential value for smarter optimisation.
  </Card>
</CardGroup>

## Sending website lead data to your CRM

When a lead is submitted on your website, send the SegmentStream user identifier along with the lead data to your CRM. This ensures consistent attribution for both consented and non-consented users while staying privacy-compliant.

Use the following SDK method to retrieve the user identifier:

```javascript theme={null}
const clientId = window.segmentstream.anonymousId();
```

* If the user has consented to cookies, this returns the `_ga` cookie value.
* If the user has not consented, it returns a generated anonymous ID.

<Warning>
  On the same page where the lead is sent to the CRM, you must also call `window.segmentstream.conversion({ type: 'lead' })`. Calling the conversion method on a different page (e.g. a redirect page) will not work for aggregated conversion attribution.
</Warning>

For full SDK setup details, see the [SegmentStream SDK guide](/project-configuration/sdk).

## Tracking ad platform lead forms

Leads generated directly on ad platforms (Meta Lead Ads, LinkedIn Lead Gen Forms, Google Ads lead extensions, TikTok Lead Generation, etc.) are collected without the user visiting your website. SegmentStream can still track and attribute these leads by creating synthetic landing pages and virtual sessions.

For a detailed implementation guide, see [How to track ad platform lead forms in analytics and CRM](/project-configuration/lead-gen-business-integration/how-to-track-ad-platform-lead-forms-in-analytics-and-crm).

## Lead scoring

SegmentStream's machine learning models score your leads by quality and potential value. This enables smarter optimisation, focusing on high-value prospects and improving marketing ROI.


# How to track ad platform lead forms in analytics and CRM
Source: https://docs.segmentstream.com/project-configuration/lead-gen-business-integration/how-to-track-ad-platform-lead-forms-in-analytics-and-crm

Create synthetic landing pages and virtual sessions to track and attribute leads generated on ad platforms like Meta, LinkedIn, Google Ads, and TikTok.

When users submit lead forms directly on ad platforms (Meta, LinkedIn, Google Ads, TikTok, etc.), they never reach your website -- meaning you lose the UTMs and client IDs that traditional analytics systems rely on.

This guide explains how to recreate synthetic landing pages, generate a Google-style Client ID (UUID), and send both to your CRM and Google Analytics 4 (GA4) for unified attribution -- even when no site visit occurs.

***

## Overview of the process

For each incoming lead (from any ad platform):

1. Capture ad metadata (campaign, ad, platform).
2. Build a **synthetic landing page URL** using UTMs.
3. Generate a **Google Client ID (UUID)**.
4. Send both fields (`landing_page`, `google_client_id`) to your **CRM**.
5. Send a synthetic **lead event** to **GA4** using the same client ID.
6. Once implemented, **SegmentStream** can automatically stitch GA4 events, CRM leads, and campaign costs -- even for leads collected inside the platforms without website visits.

***

## Why this works

Even though the user never lands on your site, the synthetic landing page and UUID create a virtual session. This lets analytics systems register a visit with proper UTMs and connect it to your CRM record, providing a unified, channel-attributed view of lead generation performance.

***

## Step 1: Generate a Google Client ID (UUID)

Instead of simulating GA4's native client ID, simply use a UUID for clarity. This makes it evident that the session was artificially generated.

```javascript theme={null}
function generateCID() {
  return crypto.randomUUID();
}
```

Example output:

```
1d52c3ab-bb40-4b23-b7a2-9266a1c89d4b
```

Store this in your CRM as `google_client_id`, and reuse the same value when sending the GA4 event.

***

## Step 2: Create synthetic landing pages

For each lead, construct a synthetic landing page URL in this format:

```
https://yourdomain.com/leadgen?utm_source={platform}&utm_medium=leadform&utm_campaign={campaign_name}&utm_content={ad_name}&cid={google_client_id}
```

This URL will never actually load; it simply represents where the lead *would* have landed if they visited your website.

### Example

```
https://yourdomain.com/leadgen?utm_source=facebook&utm_medium=leadform&utm_campaign=Summer_Sale&utm_content=Ad_1&cid=1d52c3ab-bb40-4b23-b7a2-9266a1c89d4b
```

Store this in your CRM as the field `landing_page`.

***

## Step 3: Send synthetic event to GA4

Use the GA4 Measurement Protocol endpoint:

```
https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXX&api_secret=YOUR_SECRET
```

**Payload example:**

```json theme={null}
{
  "client_id": "1d52c3ab-bb40-4b23-b7a2-9266a1c89d4b",
  "events": [{
    "name": "lead_submission",
    "params": {
      "page_location": "https://yourdomain.com/leadgen?utm_source=facebook&utm_medium=leadform&utm_campaign=summer_sale&utm_content=ad_1",
      "source_platform": "facebook",
      "form_type": "lead_form"
    }
  }]
}
```

***

## Step 4: Send data to CRM

Your CRM (HubSpot, Pipedrive, Salesforce, etc.) should include at least the following custom fields:

| Field              | Description                                    |
| ------------------ | ---------------------------------------------- |
| `landing_page`     | Synthetic URL with UTMs                        |
| `google_client_id` | UUID shared with GA4                           |
| `source_platform`  | Platform name (Meta, LinkedIn, TikTok, Google) |
| `campaign_name`    | From ad metadata                               |
| `ad_name`          | From ad metadata                               |

***

## Step 5: Platform-specific implementation

### Meta (Facebook and Instagram Lead Ads)

**Metadata available:** `ad_id`, `ad_name`, `adset_name`, `campaign_name`, `platform`

**UTM formula:**

```
utm_source=facebook&utm_medium=leadform&utm_campaign={{campaign_name}}&utm_content={{ad_name}}
```

**Automation flow:**

1. Trigger: New Lead in Facebook Lead Ads
2. Generate `google_client_id` (UUID)
3. Build `landing_page` URL
4. Send both to CRM
5. Post synthetic `lead_submission` event to GA4 via webhook

***

### LinkedIn Lead Gen Forms

**Metadata available:** `campaignName`, `adGroupName`, `creativeId`, `leadGenFormName`, `platform`

**UTM formula:**

```
utm_source=linkedin&utm_medium=leadform&utm_campaign={{campaignName}}&utm_content={{creativeId}}
```

**Automation flow:**

1. Trigger: New LinkedIn Lead
2. Generate `google_client_id`
3. Construct `landing_page` URL
4. Push to CRM
5. Send event to GA4

***

### Google Ads Lead Form Extensions

**Metadata available:** `campaign_name`, `ad_group_name`, `form_id`

**UTM formula:**

```
utm_source=google&utm_medium=leadform&utm_campaign={{campaign_name}}&utm_content={{ad_group_name}}
```

**Automation flow:**

1. Trigger: New Google Lead Form Submission
2. Generate `google_client_id`
3. Build synthetic `landing_page` URL
4. Send to CRM
5. Push to GA4

***

### TikTok Instant Forms

**Metadata available:** `campaign_name`, `adgroup_name`, `ad_name`, `platform`

**UTM formula:**

```
utm_source=tiktok&utm_medium=leadform&utm_campaign={{campaign_name}}&utm_content={{ad_name}}
```

**Automation flow:**

1. Trigger: New TikTok Lead
2. Generate `google_client_id`
3. Build synthetic `landing_page` URL
4. Send both to CRM
5. Send GA4 event via webhook

***

## Summary

| Step | Action                                            |
| ---- | ------------------------------------------------- |
| 1    | Capture ad metadata                               |
| 2    | Generate UUID as `google_client_id`               |
| 3    | Construct synthetic `landing_page` with UTMs      |
| 4    | Send to CRM                                       |
| 5    | Send synthetic GA4 event via Measurement Protocol |

Once implemented, SegmentStream will automatically stitch these leads -- aligning GA4 events, CRM leads, and ad spend data -- allowing full visibility into campaign performance even when the user never visited your website.


# Sending website lead data to your CRM
Source: https://docs.segmentstream.com/project-configuration/lead-gen-business-integration/sending-website-lead-data-to-your-crm

Send the SegmentStream user identifier along with lead data to your CRM for consistent attribution across consented and non-consented users.

<Tip>
  Before you continue, implement the [SegmentStream SDK](/project-configuration/sdk) snippet on your website.
</Tip>

When sending lead data from your website to your CRM, you should also send the user identifier provided by the SegmentStream SDK.

Instead of using the `_ga` cookie value, pass the value returned by the following method:

```javascript theme={null}
window.segmentstream.anonymousId()
```

* If the user has consented to cookies, this method will return the `_ga` cookie value.
* If the user has **not** consented, it will return a generated anonymous ID (instead of `null`).

This approach ensures that SegmentStream's aggregated attribution works for both consented and non-consented users.

## How to implement

<Steps>
  <Step title="Replace the _ga cookie">
    If your CRM currently receives the `_ga` cookie value, replace it with `window.segmentstream.anonymousId()`.
  </Step>

  <Step title="If replacement is not possible">
    Send the `anonymousId()` value to a separate field in your CRM.
  </Step>

  <Step title="Trigger the conversion event on the same page">
    On the same page where the lead is sent to the CRM, you must also call `window.segmentstream.conversion({ type: 'lead' })`.

    <Warning>
      Calling the conversion method on a different page, for example, a redirect page after the lead is sent, will **not** work for aggregated conversion attribution. The call must happen on the same page where the lead is submitted.
    </Warning>
  </Step>

  <Step title="Usage example">
    ```javascript theme={null}
    // code that sends data to the CRM
    const clientId = window.segmentstream.anonymousId();
    sendLeadToCRM({
        name: leadName,
        email: leadEmail,
        clientId: clientId
    });

    // code that sends data to SegmentStream
    window.segmentstream.conversion({
        type: 'lead'
    });
    ```
  </Step>
</Steps>

This ensures consistent attribution coverage while remaining compliant with privacy regulations.


# Integrating without IP tracking
Source: https://docs.segmentstream.com/project-configuration/no-ip-tracking

Set up SegmentStream without collecting user IP addresses by using hashed IPs and server-side geolocation.

If your organisation's privacy policy does not allow the collection or processing of user IP addresses, SegmentStream supports an alternative setup.

Instead of sending raw IP addresses, you can **hash** the IP (with salt) and **enrich it with geolocation data** on your side, before passing it to the SegmentStream data layer.

This approach ensures:

* No personally identifiable IP data is shared with SegmentStream.
* You still provide necessary contextual information (such as country, city, or region).
* Compliance with stricter data protection requirements (e.g. GDPR).

## 1. Required fields in the data layer

```javascript theme={null}
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: 'user_context',
  ip_hash: '1e4b9f1a3d7e... (hashed and salted value)',
  country: 'DE',
  region: 'Berlin',
  city: 'Berlin',
});
```

### Field descriptions

| Field     | Type     | Description                                                                                            |
| --------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `ip_hash` | `string` | Hashed (and salted) IP address. The hash ensures anonymity, and the salt prevents reverse-engineering. |
| `country` | `string` | Country code (e.g. `"DE"`, `"FR"`, `"US"`).                                                            |
| `region`  | `string` | Region or state.                                                                                       |
| `city`    | `string` | City name.                                                                                             |

## 2. How to prepare the IP address

All processing, including normalisation and hashing, should happen on your server. This ensures the raw IP address never leaves your infrastructure and that only anonymised data is shared with SegmentStream.

### Step 1: Normalise IPv6 addresses (server-side)

IPv6 addresses are more detailed than IPv4 and can include device-specific parts. To ensure privacy, the IPv6 address should be normalised to keep only the network portion (the first half) and replace the device-specific bits with zeros.

| Type       | IPv6 example                              | Meaning                                 |
| ---------- | ----------------------------------------- | --------------------------------------- |
| Full IPv6  | `2001:0db8:85a3:0000:0000:8a2e:0370:7334` | Device-level identifier                 |
| Normalised | `2001:0db8:85a3:0000:0000:0000:0000:0000` | Network-level identifier (safe to hash) |

```javascript theme={null}
// Run on your backend
function normalizeIPv6(ip) {
  if (!ip.includes(':')) return ip; // IPv4 - no normalization
  const segments = ip.split(':').slice(0, 4);
  while (segments.length < 8) segments.push('0000');
  return segments.join(':');
}
```

<Note>
  If the IP is IPv4, you can skip this step.
</Note>

### Step 2: Apply salted hashing (server-side)

After normalisation, hash the IP using a secure algorithm like SHA-256 and a private salt stored safely on your backend (e.g. in environment variables).

<Warning>
  * Do **not** hash or salt IPs in the browser.
  * The salt must remain secret and never be exposed to the client.
  * Only send the hashed IP and geo data to the frontend.
</Warning>

```javascript theme={null}
import crypto from 'crypto';

const SALT = process.env.IP_HASH_SALT; // store securely in environment variables

function hashIP(ip) {
  return crypto.createHash('sha256').update(ip + SALT).digest('hex');
}
```

Example output:

```text theme={null}
f2c992f0a9f8d5c8b87e1a2b36a52e5bce9df51de60cdb3eaf5d66a6dfdfe281
```

### Step 3: Example of each stage

| Step               | Description                         | Example                                      |
| ------------------ | ----------------------------------- | -------------------------------------------- |
| Full IPv6          | Original address                    | `2001:0db8:85a3:0000:0000:8a2e:0370:7334`    |
| Normalised         | Network-only portion (safe to hash) | `2001:0db8:85a3:0000:0000:0000:0000:0000`    |
| Hashed (with salt) | Final anonymised value              | `f2c992f0a9f8d5c8b87e1a2b36a52e5bce9df51...` |

## 3. Geolocation data

Use your own geolocation service (e.g. MaxMind, IP2Location, or a cloud provider's API) to extract country and region information before hashing.

## 4. Example architecture

Below is a complete setup showing where each process occurs.

### Server (Node.js / Python / etc.)

```javascript theme={null}
app.get('/api/user-context', async (req, res) => {
  const ip = getClientIP(req); // your logic for IP extraction
  const normalized = normalizeIPv6(ip);
  const hashed = hashIP(normalized);
  const geo = await lookupGeo(ip); // from your geolocation provider

  res.json({
    ip_hash: hashed,
    country: geo.country,
    region: geo.region,
    city: geo.city,
  });
});
```

### Client (browser)

```javascript theme={null}
(async () => {
  const context = await fetch('/api/user-context').then(r => r.json());

  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'user_context',
    ip_hash: context.ip_hash,
    country: context.country,
    region: context.region,
    city: context.city,
  });
})();
```

This way:

* The raw IP never leaves your infrastructure.
* The client receives only anonymised and geo-enriched data.
* SegmentStream operates in full privacy compliance.

## 5. Summary checklist

* [ ] Normalise IPv6 addresses on the server.
* [ ] Hash IPs with a private salt on the server.
* [ ] Send only hashed IP + geo data to the browser.
* [ ] Never expose the salt or raw IP in client code.
* [ ] Ensure consistency and privacy compliance.


# Project configuration
Source: https://docs.segmentstream.com/project-configuration/overview

Set up your SegmentStream project: data warehouse, event tracking, identity graph, SDK, data sources, conversions, and attribution models.

Configure every aspect of your SegmentStream project. Select a section below to get started.

<CardGroup>
  <Card title="Data warehouse" icon="database" href="/project-configuration/data-warehouse">
    Connect a data warehouse to store and process your project data.
  </Card>

  <Card title="Events tracking" icon="chart-scatter" href="/project-configuration/events-tracking">
    Configure event tracking to feed ML models and power attribution.
  </Card>

  <Card title="Identity graph" icon="users" href="/project-configuration/identity-graph">
    Stitch user sessions across browsers, devices, and channels.
  </Card>

  <Card title="SegmentStream SDK" icon="code" href="/project-configuration/sdk">
    Install the SDK to collect engagement signals and improve attribution.
  </Card>

  <Card title="Data sources" icon="plug" href="/project-configuration/data-sources/overview">
    Connect advertising platforms to import cost and campaign data.
  </Card>

  <Card title="Conversions" icon="bullseye" href="/project-configuration/conversions">
    Define the business conversions you want to track and attribute.
  </Card>

  <Card title="Attribution models" icon="sitemap" href="/project-configuration/attribution-models">
    Choose and configure the attribution models for your reports.
  </Card>

  <Card title="Self-reported attribution" icon="clipboard-question" href="/project-configuration/self-reported-attribution">
    Collect "how did you hear about us?" survey data for attribution.
  </Card>
</CardGroup>

## Additional guides

<CardGroup>
  <Card title="Integrating without IP tracking" icon="shield-halved" href="/project-configuration/no-ip-tracking">
    Set up SegmentStream without collecting user IP addresses.
  </Card>

  <Card title="Lead gen business integration" icon="address-card" href="/project-configuration/lead-gen">
    Attribute leads from websites and ad platform lead forms.
  </Card>
</CardGroup>


# SegmentStream SDK
Source: https://docs.segmentstream.com/project-configuration/sdk

Install the SegmentStream SDK to preserve click IDs, send cookieless pings, and enable privacy-safe conversion tracking.

The SegmentStream SDK adds a first-party measurement layer alongside GA4. It preserves ad platform click IDs during internal navigation, sends cookieless pings to SegmentStream, and can send conversion events through `segmentstream.conversion()`.

## What the SDK does

* **Click ID propagation**: preserves ad platform click IDs, such as `gclid`, `fbclid`, `ttclid`, `msclkid`, `li_fat_id`, `ScCid`, `rdt_cid`, `twclid`, `dclid`, and `epik`, across internal links, `window.open`, and History API navigation.
* **Cookieless pings**: sends page-load and first-interaction pings to SegmentStream without relying on analytics cookies.
* **Conversion tracking**: sends direct conversion events from the website through `segmentstream.conversion()`.

## Installing the SDK via GTM

<Steps>
  <Step title="Create a new tag">
    In Google Tag Manager, go to **Tags** and click **New**.

    <img alt="GTM Tags page with New button" />
  </Step>

  <Step title="Configure the tag">
    Name the tag **SegmentStream SDK** and choose the **Custom HTML** tag type.

    <img alt="Selecting Custom HTML tag type" />
  </Step>

  <Step title="Add the SDK code">
    Enter the following code. Replace `ID PROVIDED BY MANAGER` with the ID provided by your SegmentStream account manager.

    ```html theme={null}
    <script>(function(){var s=window.segmentstream=window.segmentstream||{};
    s._q=s._q||[];['init','conversion','anonymousId'].forEach(function(m){
    s[m]=function(){s._q.push([m,Array.prototype.slice.call(arguments)])}})})();</script>

    <script async src="https://cdn.segmentstream.com/sdk/v1/segmentstream.min.js"></script>
    <script>segmentstream.init("ID PROVIDED BY MANAGER");</script>
    ```
  </Step>

  <Step title="Set firing options">
    Expand **Advanced Settings** and select **Once per page** in **Tag firing options**.
  </Step>

  <Step title="Add a trigger">
    Choose **All Pages** in the **Firing Triggers** option.

    <img alt="SDK tag with All Pages trigger" />
  </Step>
</Steps>

## Configuring SDK settings

By default, the SegmentStream SDK enables click ID propagation and cookieless pings. Browser storage is disabled unless you explicitly enable it.

Available settings:

| Setting                | Default | Description                                                                                        |
| ---------------------- | ------: | -------------------------------------------------------------------------------------------------- |
| `click_id_propagation` |  `true` | Preserves ad platform click IDs across internal links, `window.open`, and History API navigation.  |
| `cookieless_pings`     |  `true` | Sends page-load and first-interaction pings to SegmentStream without relying on analytics cookies. |
| `local_storage`        | `false` | Enables localStorage for attribution touchpoints and conversion deduplication state.               |

Add the settings block before the SDK script only when you need to override the defaults:

```html theme={null}
<script>
  window.segmentstream_sdk_settings = {
    click_id_propagation: true,
    cookieless_pings: true,
    local_storage: false
  };
</script>
```

<Warning>
  Enable `local_storage` only when your consent and privacy setup allows browser storage. When `local_storage` is `false`, the SDK does not store attribution touchpoints or conversion deduplication state in the browser.
</Warning>

## Aggregated conversions measurement

The SegmentStream SDK supports conversion tracking through a strict object API. Use it when you need SegmentStream to receive a direct conversion signal from the website, such as a purchase, lead, signup, or subscription.

### Implementation through GTM

<Steps>
  <Step title="Create a new tag">
    In Google Tag Manager, go to **Tags**, click **New**, name the tag **SegmentStream Conversion Tracking**, and choose the **Custom HTML** tag type.
  </Step>

  <Step title="Add the conversion code">
    In the HTML block, insert the appropriate code for your conversion type:

    <Tabs>
      <Tab title="Purchase (with order ID)">
        Replace `ORDER_ID` and `ORDER_VALUE` with the variables used in your GA4 conversion tag.

        ```html theme={null}
        <script>
        segmentstream.conversion({
          type: 'purchase',
          id: 'ORDER_ID',
          value: ORDER_VALUE,
          currency: 'USD'
        });
        </script>
        ```
      </Tab>

      <Tab title="Lead (no order ID)">
        ```html theme={null}
        <script>
        segmentstream.conversion({
          type: 'lead'
        });
        </script>
        ```
      </Tab>

      <Tab title="Signup (with value)">
        ```html theme={null}
        <script>
        segmentstream.conversion({
          type: 'signup',
          value: ORDER_VALUE,
          currency: 'USD'
        });
        </script>
        ```
      </Tab>
    </Tabs>

    <img alt="Conversion tracking tag configuration" />
  </Step>

  <Step title="Set the trigger">
    Set the trigger for this tag to match the trigger used by your GA4 conversion tag.
  </Step>

  <Step title="Configure tag sequencing">
    In **Tag Sequencing**, make sure the **SegmentStream SDK** tag fires **before** this tag.
  </Step>

  <Step title="Save and publish">
    Save and publish the changes.
  </Step>
</Steps>

### Implementation via SDK

You can trigger a conversion directly using the SDK method:

```javascript theme={null}
segmentstream.conversion({
  type: 'purchase',    // Required: event type, such as 'purchase', 'lead', or 'signup'
  id: 'ORDER_ID',      // Optional: unique identifier for the conversion
  value: ORDER_VALUE,  // Optional: numeric value of the conversion
  currency: 'USD'      // Optional: currency code
});
```

**Examples:**

<CodeGroup>
  ```javascript Purchase theme={null}
  segmentstream.conversion({
    type: 'purchase',
    id: 'ORD-12345',
    value: 199.99,
    currency: 'USD'
  });
  ```

  ```javascript Lead theme={null}
  segmentstream.conversion({
    type: 'lead'
  });
  ```

  ```javascript Subscription theme={null}
  segmentstream.conversion({
    id: 'SUB-67890',
    type: 'subscription'
  });
  ```
</CodeGroup>

This function should be called on the conversion confirmation page, such as the order success or thank-you page, after the SegmentStream SDK is initialised.

### Sending lead data to your CRM

When sending lead data from your website to your CRM, pass the user identifier provided by the SegmentStream SDK instead of using the `_ga` cookie value:

```javascript theme={null}
window.segmentstream.anonymousId()
```

* If the user has consented to cookies, this method returns the `_ga` cookie value.
* If the user has **not** consented, it returns a generated anonymous ID (instead of `null`).

This approach ensures that SegmentStream's aggregated attribution works for both consented and non-consented users.

**How to implement:**

1. If your CRM currently receives the `_ga` cookie value, replace it with `window.segmentstream.anonymousId()`.
2. If replacement is not possible, send the `anonymousId()` value to a separate field in your CRM.
3. On the same page where the lead is sent to the CRM, call `window.segmentstream.conversion({ type: 'lead' })`.

<Warning>
  Calling the conversion method on a different page (for example, a redirect page after the lead is sent) will not work for aggregated conversion attribution. The call must happen on the same page where the lead is submitted.
</Warning>

```javascript theme={null}
// Send data to the CRM
const clientId = window.segmentstream.anonymousId();
sendLeadToCRM({
    name: leadName,
    email: leadEmail,
    clientId: clientId
});

// Send data to SegmentStream
window.segmentstream.conversion({
    type: 'lead'
});
```

## Verifying the SDK

<Steps>
  <Step title="Confirm the SDK ping">
    After page load, open the browser Network tab and look for a POST request to `https://track.segmentstream.com/ds/PROJECT_ID` with `eventName: "ping"`.
  </Step>

  <Step title="Confirm click ID propagation">
    Open a page with a test click ID, such as `?gclid=test`, then click an internal link. The click ID should remain in the URL after navigation.
  </Step>

  <Step title="Confirm conversion tracking">
    Trigger the conversion action and look for a POST request to `https://track.segmentstream.com/ds/PROJECT_ID` with `eventName: "conversion"` and `conversionEventName` matching the `type` value you passed to `segmentstream.conversion()`.
  </Step>

  <Step title="Check the console">
    The browser console should not show SegmentStream errors. If you see `SDK must be initialized with project_id`, check that `segmentstream.init("ID PROVIDED BY MANAGER")` runs before conversion tracking.
  </Step>
</Steps>


# SegmentStream AI Prerequisites
Source: https://docs.segmentstream.com/project-configuration/segmentstream-ai-prerequisites

Prepare your Google Cloud project and GA4 BigQuery export so you are ready to connect to SegmentStream AI when access is granted.

This guide describes the steps you need to complete **before** you can connect to SegmentStream AI. By following these steps now, you will be ready to get started as soon as access is granted to you.

## Overview

To use SegmentStream AI, you need:

1. A Google Cloud project with BigQuery enabled and billing set up.
2. A GA4 BigQuery export configured to send event data to your BigQuery project.

## Step 1. Prepare your Google Cloud project

Follow the steps below to make sure your Google Cloud project is ready.

### 1.1 Create a Google Cloud Platform account

BigQuery is a part of Google Cloud Platform. To use BigQuery you need to have a Google Cloud Platform account.

<Steps>
  <Step title="Navigate to Google Cloud Platform">
    Go to the [Google Cloud Platform page](https://cloud.google.com/) and click **Get started for free**.

    <img alt="Google Cloud Platform get started" />
  </Step>

  <Step title="Log in to your Google Account">
    Log in to your Google Account.
  </Step>

  <Step title="Complete registration">
    Fill in the registration form. Provide valid payment details — it's important, as you need an account with an active payment method to use BigQuery.
  </Step>
</Steps>

### 1.2 Set up a billing account

To use BigQuery you need an active billing account so that you'll be able to use Google Cloud Platform resources.

Free Tier Google Cloud accounts don't support some BigQuery services which are required.

#### Upgrading a Free Tier account

Go to the [main page of your Google Cloud Platform](https://console.cloud.google.com/) project and click **ACTIVATE FULL ACCOUNT**.

<img alt="Activate full account" />

More information on upgrading your account can be found [here](https://cloud.google.com/free/docs/gcp-free-tier#how-to-upgrade).

#### Checking billing account status

If you don't have an **ACTIVATE FULL ACCOUNT** button on the main project page, check that you have an active billing account with a valid payment method:

<Steps>
  <Step title="Go to billing">
    Go to the [Google Cloud Platform Billing page](https://console.cloud.google.com/billing).
  </Step>

  <Step title="Check billing accounts">
    Check that you have at least one billing account with active status.

    <img alt="Billing accounts" />
  </Step>

  <Step title="Link billing to project">
    Click on **MY PROJECTS**, and confirm that the billing account is linked to your project. If it isn't linked, click the "more icon" then **Change billing** to link an active billing account.

    <img alt="Billing my projects" />
  </Step>

  <Step title="Verify account status">
    Click on the account name and follow instructions to set the status to active if it is different.

    <img alt="Billing account status" />
  </Step>

  <Step title="Validate payment info">
    Validate your payment info (1) and check that you don't have any critical (red) billing health check issues (2).

    <img alt="Billing health check" />
  </Step>
</Steps>

If you experience an issue with setting up a billing account [consult the documentation on billing accounts](https://cloud.google.com/billing/docs/how-to/manage-billing-account).

### 1.3 Create a Google Cloud project

<Steps>
  <Step title="Navigate to Manage resources">
    Navigate to the [Manage resources](https://console.cloud.google.com/cloud-resource-manager?walkthrough_id=resource-manager--create-project) page in the Google Cloud console.
  </Step>

  <Step title="Select organisation">
    On the **Select organisation** drop-down list at the top of the page, select the organisation resource in which you want to create a project. If you are a free trial user, skip this step, as this list does not appear.
  </Step>

  <Step title="Create the project">
    Click **Create Project**. In the **New Project** window that appears, enter a project name and select a billing account as applicable.
  </Step>

  <Step title="Set parent organisation">
    Enter the parent organisation or folder resource in the Location box. That resource will be the hierarchical parent of the new project. If No organisation is an option, you can select it to create your new project as the top level of its own resource hierarchy.
  </Step>

  <Step title="Finish creation">
    When you're finished entering new project details, click **Create**.
  </Step>
</Steps>

## Step 2. Set up GA4 BigQuery export

Once your Google Cloud project is ready, you need to link your Google Analytics 4 property to BigQuery so that event data is exported automatically.

### 2.1 Link your GA4 property to BigQuery

This process must be completed by a user with **Owner** access to the Google Cloud project. The Owner role is assigned to the user who created the project, but you can also grant this permission through the [Google Cloud Project IAM](https://console.cloud.google.com/iam-admin/iam) page.

<Steps>
  <Step title="Select your GA4 property">
    Go to [Google Analytics 4](https://analytics.google.com/) and select the property where your data is collected.
  </Step>

  <Step title="Open Admin settings">
    Click on the **Admin** button.
  </Step>

  <Step title="Navigate to BigQuery links">
    In the **Product Links** section, click **BigQuery links**.

    <img alt="GA4 BigQuery links page" />
  </Step>

  <Step title="Configure the BigQuery link">
    1. Click **Link** > **Choose a BigQuery project**.
    2. Select the BigQuery project you created in Step 1.
    3. Select the **Data location** that matches your business's region.
    4. Enable both the **Daily** and **Streaming** export types.
    5. Make sure no events are excluded.
    6. Click **Submit**.

       <img alt="GA4 BigQuery link setup" />
  </Step>
</Steps>

<Info>
  We recommend enabling both the **Daily** and **Streaming (best-effort)** export types. The daily export provides a complete dataset once per day, while the streaming export ensures near real-time data availability.
</Info>

### 2.2 Verify the export

Once the GA4 BigQuery link is set up, data should start flowing to your BigQuery project within 24 hours. You can verify this by checking your BigQuery project for newly created GA4 event tables.

## What's next

Once you have completed the steps above, your environment is fully prepared. When you receive access to SegmentStream AI, you will be able to connect right away without any additional setup on the Google Cloud or GA4 side.


# Self-reported attribution
Source: https://docs.segmentstream.com/project-configuration/self-reported-attribution

Recover lost conversions from Direct, Brand, or Organic channels by asking users how they heard about you and mapping responses to paid or owned channels.

Self-reported attribution helps recover lost conversions from "Direct," "Brand," or "Organic" channels by asking users directly how they heard about your brand and then mapping these responses to the appropriate paid or owned channels.

## Add the "How did you hear about us?" field

Add an optional "How did you hear about us?" field to your registration, checkout, or lead form. Free-text is preferred, but you can also provide a list of answers to select from.

## Store responses in GA4 or CRM

You can store the user's answer as an event parameter in GA4 (for example, `self_reported_source`) or in your CRM. Both the **Client ID** and the **response** must be available in the source where this data is stored.

<Tabs>
  <Tab title="GA4 setup">
    When the form is submitted, pass the user's answer to a custom event parameter, for example `self_reported_source`.

    In Google Tag Manager, configure this in your GA4 event tag by adding a new **Event Parameter** and setting its value to the variable that contains the user's answer.

    <img alt="GA4 event parameter configuration in GTM" />
  </Tab>

  <Tab title="CRM setup">
    For CRM systems, pass the same value into one of the lead parameters, also named `self_reported_source` for example. The **Client ID** must be stored in the CRM together with this value to allow correct attribution stitching.
  </Tab>
</Tabs>

### Testing the implementation

<Steps>
  <Step title="Complete test forms">
    Open your website in a test environment and complete the form using different responses.
  </Step>

  <Step title="Verify GA4 events">
    In **GA4 DebugView**, confirm that the event is being sent correctly and that `self_reported_source` appears as a parameter.
  </Step>

  <Step title="Verify CRM records">
    If using a CRM, verify that the same field is populated correctly in the lead or transaction records.
  </Step>

  <Step title="Check Client ID">
    Ensure that the **Client ID** is recorded together with the self-reported value.
  </Step>

  <Step title="Validate event firing">
    Validate that the event fires once per submission and that the data appears within a few minutes in GA4 Realtime or CRM logs.
  </Step>

  <Step title="Deploy to production">
    After successful testing, move the setup to production.
  </Step>
</Steps>

## Define business logic

After collecting sufficient responses, define which responses and how you would like to map them to your business channels. For example:

| User response                    | Mapped channel |
| -------------------------------- | -------------- |
| "Friend," "Local," or "Shop"     | Referral       |
| "YouTube"                        | Influencer     |
| "Instagram"                      | Meta           |
| "Newsletter," "Email from brand" | Email          |

Keep a lookup table for consistent classification and to handle new response types as they appear. Even before re-attribution, the responses themselves provide insights into how customers perceive and discover your brand, helping identify which channels or touchpoints drive the strongest brand awareness and engagement.

## Re-attribute conversions

SegmentStream automatically classifies free-text responses using AI based on the business logic you define. It then uses classified data to re-attribute conversions that were originally labeled as Direct, Brand, Organic, etc. to their true paid or owned sources. The corrected attribution is then reflected in reports, improving visibility into real channel effectiveness.


# Quick start
Source: https://docs.segmentstream.com/quick-start

Set up your first SegmentStream project, from account creation through reports and marketing mix optimization.

This guide walks you through setting up your first SegmentStream project, starting from account creation and ending with built-in reports and marketing mix optimization.

<Steps>
  <Step title="Create an account">
    Use the link provided by your SegmentStream manager. You will be asked to enter your name, the name of your company, and the country where your business resides.

    <img alt="SegmentStream account creation form" />
  </Step>

  <Step title="Create a project">
    Enter the project name as it will appear in the SegmentStream interface, the currency and timezone for reporting, and the location of the servers that will process the project's data.

    <img alt="SegmentStream project creation form" />
  </Step>

  <Step title="Add team members">
    To invite other people to the project, click **+ INVITE** on the Members page, enter their email, select the permissions, and click **SEND**.

    <img alt="Team member invitation page" />
  </Step>

  <Step title="Configure data warehouse">
    Connect a data warehouse to store and process your project's data. Google BigQuery is the recommended option -- read the [data warehouse guide](/project-configuration/data-warehouse) for setup instructions.

    <Tip>
      If using your own BigQuery instance is not feasible, you can use a SegmentStream-hosted data warehouse. Contact your SegmentStream manager to enable this option.
    </Tip>
  </Step>

  <Step title="Set up event tracking">
    If Google Analytics 4 is already implemented on your website or app, integrating event tracking through the native GA4 BigQuery Link feature is the most straightforward approach.

    Refer to the [event tracking guide](/project-configuration/events-tracking) for detailed information and additional options.

    <img alt="Event tracking configuration" />
  </Step>

  <Step title="Connect advertising platforms">
    Follow the [data sources guide](/project-configuration/data-sources/overview) to connect your advertising platforms.

    <img alt="Data sources configuration page" />
  </Step>

  <Step title="Create conversions">
    For an e-commerce website, the main conversion is typically the purchase event. To track a purchase conversion based on your GA4 data:

    1. Navigate to the **Conversions** page
    2. Click **+ ADD** and select **Simple conversion**
    3. Enter a conversion name (for example, "Purchase")
    4. Make sure the Purchase conversion event type is selected
    5. Click **SAVE**

       <img alt="Conversion creation form" />

    Follow the [conversions guide](/project-configuration/conversions) if your website does not track purchases or you need to track other types of conversions.
  </Step>

  <Step title="Configure attribution reports">
    Go to the reports page and add the conversion you created to every report. After a full day has passed since event tracking was set up, you will be able to see data on sessions and ad platform costs.

    Refer to the [Attribution documentation](/attribution/overview) to understand how to use reports to their full potential.

    <img alt="Attribution report configuration" />
  </Step>

  <Step title="Set up your optimization portfolio">
    Once your data starts flowing, create an optimization portfolio to use the SegmentStream marketing mix optimization tool.

    Refer to the [Optimization documentation](/optimization/overview) for more information.
  </Step>

  <Step title="Implement SegmentStream SDK">
    To improve user stitching and attribution quality, install the SegmentStream SDK. The SDK preserves ad platform click IDs during internal navigation and sends cookieless pings for first-party measurement.

    Refer to the [SDK guide](/project-configuration/sdk) for detailed implementation instructions. If you need help with the setup, contact support.
  </Step>

  <Step title="Setup complete">
    You can now use the portfolio dashboards and reports to make informed decisions on your marketing strategy.
  </Step>
</Steps>

## What's next?

Explore reporting using different attribution models such as **First Click** and **Multi-Touch** to better understand the impact of each channel across the user journey. Learn more in the [Attribution models](/project-configuration/attribution-models) documentation.