> ## Documentation Index
> Fetch the complete documentation index at: https://docs.segmentstream.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SegmentStream 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 src="https://mintcdn.com/segmentstream/fSGYTtkHEv2DXb5X/images/project-configuration/sdk-gtm-new-tag.png?fit=max&auto=format&n=fSGYTtkHEv2DXb5X&q=85&s=aa16bdb6a56dc18cc0b39ae4e3cf96a7" alt="GTM Tags page with New button" width="2486" height="852" data-path="images/project-configuration/sdk-gtm-new-tag.png" />
  </Step>

  <Step title="Configure the tag">
    Name the tag **SegmentStream SDK** and choose the **Custom HTML** tag type.

    <img src="https://mintcdn.com/segmentstream/fSGYTtkHEv2DXb5X/images/project-configuration/sdk-gtm-custom-html.png?fit=max&auto=format&n=fSGYTtkHEv2DXb5X&q=85&s=7b235c7664f4b8bde64f6bde9e050e67" alt="Selecting Custom HTML tag type" width="3584" height="786" data-path="images/project-configuration/sdk-gtm-custom-html.png" />
  </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 src="https://mintcdn.com/segmentstream/fSGYTtkHEv2DXb5X/images/project-configuration/sdk-gtm-all-pages.png?fit=max&auto=format&n=fSGYTtkHEv2DXb5X&q=85&s=aec2282ec6bb9d0ba38d2230cbde544d" alt="SDK tag with All Pages trigger" width="2740" height="1748" data-path="images/project-configuration/sdk-gtm-all-pages.png" />
  </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 src="https://mintcdn.com/segmentstream/fSGYTtkHEv2DXb5X/images/project-configuration/sdk-gtm-conversion-tracking.png?fit=max&auto=format&n=fSGYTtkHEv2DXb5X&q=85&s=0f8b5018d07c231f58584b2b83bc5842" alt="Conversion tracking tag configuration" width="2112" height="1574" data-path="images/project-configuration/sdk-gtm-conversion-tracking.png" />
  </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>