Skip to content

Improve GTM guides #225

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 8, 2025
Merged

Improve GTM guides #225

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
95ada7b
Improve GTM guides
steven-tey Aug 8, 2025
6308e72
fix gtm gudies
steven-tey Aug 8, 2025
b82534a
Update conversions/leads/google-tag-manager.mdx
steven-tey Aug 8, 2025
dd1a239
Update conversions/leads/google-tag-manager.mdx
steven-tey Aug 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
306 changes: 191 additions & 115 deletions conversions/leads/google-tag-manager.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,128 +24,202 @@ Before you get started, make sure you follow the [Dub Conversions quickstart gui

To track lead conversion events with Google Tag Manager, you'll need to set up a server container and configure a custom client to handle Dub conversion events.

<Steps>

<Step title="Set up Server Container">

In Google Tag Manager, you'll need to use an existing server container or create a new one. Server containers are the foundation for server-side tracking and allow you to process events before they reach their final destinations.

- If you already have a server container set up, you can use that
- If not, create a new server container in your GTM workspace

</Step>

<Step title="Import Dub GTM Server Client Template">

Add a new Client Template using the import option:

1. In your server container, go to **Client Templates** → **New**
2. Click **Import** and upload the [Dub GTM Server Client template](https://github.com/dubinc/gtm-server-client-template)

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-server-client-template.png"
alt="GTM Server Client Template"
width="1440"
height="1024"
/>
</Frame>

</Step>

<Step title="Create Dub Server Client">

Next, create a new Client using the imported template:

1. In your server container, go to **Clients** → **New**
2. Select the **Dub GTM Server Client** template from **Custom**
3. Name the client "Dub Server Client" (or any descriptive name)
4. Set the **Request Path** to `/dub/track`
5. Optionally enable debug logging for troubleshooting

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-server-client.png"
alt="GTM Server Client"
width="1440"
height="1024"
/>
</Frame>

**Note:** Clients in GTM Server are adapters that act as bridges between the software running on a user's device and your server container. They receive requests and transform them into events that can be processed by tags.

</Step>

<Step title="Import Dub GTM Server Tag Template">

Next, import the Dub GTM Server Tag template to handle lead tracking:

1. In your server container, go to **Tags** → **New**
2. Click **Import** and upload the [Dub GTM Server Tag template](https://github.com/dubinc/gtm-server-tag-template)
3. This template is specifically designed to send conversion events directly to Dub

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-server-tag-template.png"
alt="Dub GTM Server Tag Template"
width="1440"
height="1024"
/>
</Frame>

</Step>

<Step title="Add Lead Tracking Tag">

Next, create a new tag for lead tracking with proper mapping:

1. In your server container, go to **Tags** → **New**
2. Select the **Dub Conversion Tag** template from **Custom**
3. Name the tag "Dub Lead Tracking" (or any descriptive name)
4. Configure the tag settings:

- **Dub API Key**: Enter your [Dub API key](https://dub.co/docs/api-reference/tokens) (starts with `dub_`)
- **Event**: Select "Track lead"
- **Click ID**: Map to the `clickId` from the Dub Server Client event data
- **Customer External ID**: Map to the `customerExternalId` from the event data
- **Event Name**: Map to the `eventName` from the event data (e.g., "Sign Up")
- **Customer Name**: Map to the `customerName` from the event data
- **Customer Email**: Map to the `customerEmail` from the event data
- **Customer Avatar**: Map to the `customerAvatar` from the event data (optional)
- **Event Quantity**: Map to the `eventQuantity` from the event data (default: 1)
- **Mode**: Set to "async" for non-blocking requests

5. **Triggering**: Configure when the tag should fire:
- Click **Triggering** in the tag configuration
- Click **+** to add a new trigger
- Select **Custom Event** as the trigger type
- Set the **Event Name** to match the event name from the Dub Server Client. Default is `dub_conversion`
- Add a condition to filter for lead events:
- **Variable**: Select a variable that contains the event type
- **Operator**: Equals
- **Value**: "Sign Up"
- Name the trigger "Dub Lead Event Trigger" and save it

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-track-lead-tag.png"
alt="GTM Lead Tracking Tag"
width="1440"
height="1024"
/>
</Frame>

</Step>

</Steps>
### 1. Set up GTM Server Container

In Google Tag Manager, you'll need to use an existing server container or [create a new one](https://youtu.be/waqBSk3vkko). Server containers are the foundation for server-side tracking and allow you to process events before they reach their final destinations.

- If you already have a server container set up, you can use that
- If not, [create a new server container in your GTM workspace](https://developers.google.com/tag-platform/learn/sst-fundamentals/4-sst-setup-container)

### 2. Import Dub GTM Server Client Template

Inside your GTM server container, navigate to the **Templates** tab. Under **Client Templates**, click the **New** button.

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-new-client-template.png"
alt="GTM New Client Template"
width="1440"
height="1024"
/>
</Frame>

This will open up the **Template Editor**. In the top right corner, click on the **⋮** button and select **Import**.

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-import-client-template.png"
alt="GTM Import Client Template"
width="1440"
height="1024"
/>
</Frame>

Download the [gtm-server-client-template/template.tpl](https://raw.githubusercontent.com/dubinc/gtm-server-client-template/main/template.tpl) file and upload it to the Template Editor. You'll see a preview of the template:
<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-server-client-template.png"
alt="GTM Server Client Template"
width="1440"
height="1024"
/>
</Frame>

Click the **Save** button in the top right to save the template.

### 3. Create Dub Server Client

Next, you'd want to create a new GTM Server Client using the imported template.

In your GTM server container, navigate to the **Clients** tab and click **New**.

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-new-server-client.png"
alt="GTM New Server Client"
width="1440"
height="1024"
/>
</Frame>

This will open up the client configuration page, where you can choose a client type to begin setup. Under **Custom**, select the **Dub GTM Server Client** template that you created in step 2.

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-choose-client-type.png"
alt="GTM Choose Client Type"
width="1440"
height="1024"
/>
</Frame>

Make sure your client configuration is set to the following:

- Client Name: **Dub GTM Server Client**
- Priority: **0**
- Request Path: `/dub/track`
- Debug Logging: (optional)

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-server-client.png"
alt="GTM Server Client"
width="1440"
height="1024"
/>
</Frame>

<Note>
Clients in GTM Server are adapters that act as bridges between the software
running on a user's device and your server container. They receive requests
and transform them into events that can be processed by tags.
</Note>

### 4. Import Dub GTM Server Tag Template

Next, you'll want to import the Dub GTM Server Tag template to handle lead tracking.

In your GTM server container, navigate to the **Templates** tab once again. Under **Tag Templates**, click the **New** button.

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-new-tag-template.png"
alt="GTM New Tag Template"
width="1440"
height="1024"
/>
</Frame>

This will open up the **Template Editor**. In the top right corner, click on the **⋮** button and select **Import**.

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-import-client-template.png"
alt="GTM Import Client Template"
width="1440"
height="1024"
/>
</Frame>

Download the [gtm-server-tag-template/template.tpl](https://raw.githubusercontent.com/dubinc/gtm-server-tag-template/main/template.tpl) file and upload it to the Template Editor. You'll see a preview of the template:
<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-server-tag-template.png"
alt="Dub GTM Server Tag Template"
width="1440"
height="1024"
/>
</Frame>

Click the **Save** button in the top right to save the template.

### 5. Add Lead Tracking Tag

Last but not least, you'll want to create a new GTM Server Tag using the imported template.

In your GTM server container, navigate to the **Tags** tab and click **New**.

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-new-tag.png"
alt="GTM New Tag"
width="1440"
height="1024"
/>
</Frame>

This will open up the tag configuration page. Under **Tag Configuration**, select the **Dub Conversion Tag** server tag template that you created in step 4.

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-choose-tag-type.png"
alt="GTM Choose Tag Type"
width="1440"
height="1024"
/>
</Frame>

Make sure your tag configuration is set to the following:

- **Dub API Key**: Your [Dub API key](https://dub.co/docs/api-reference/tokens) (starts with `dub_`)
- **Event**: Select "Track lead" from the dropdown
- **Click ID**: `clickId` from the Dub Server Client event data
- **Customer External ID**: `customerExternalId` from the event data
- **Event Name**: `eventName` from the event data (e.g., "Sign Up")
- **Customer Name**: `customerName` from the event data
- **Customer Email**: Map to the `customerEmail` from the event data
- **Customer Avatar**: Map to the `customerAvatar` from the event data (optional)
- **Event Quantity**: Map to the `eventQuantity` from the event data (default: 1)

<Frame>
<img
src="/images/conversions/google-tag-manager/gtm-track-lead-tag.png"
alt="GTM Lead Tracking Tag"
width="1440"
height="1024"
/>
</Frame>

Under the **Triggering** section, configure when the tag should fire:

- Click **+** to add a new trigger
- Select **Custom Event** as the trigger type
- Set the **Event Name** to match the event name from the Dub Server Client. Default is `dub_conversion`
- Add a condition to filter for lead events:
- **Variable**: Select a variable that contains the event type
- **Operator**: Equals
- **Value**: "Sign Up"
- Name the trigger "Dub Lead Event Trigger" and save it

<LeadsAttributes />

## Testing your setup

You can test your GTM server setup by sending a curl request to your server URL with the appropriate query parameters:

```bash
<CodeGroup>

```bash cURL
curl "https://server-side-tagging-xxx-uc.a.run.app/dub/track/lead?\
dub_id=pAzVZ3jzwZXcLMDT&\
eventName=Sign%20Up&\
Expand All @@ -157,6 +231,8 @@ eventQuantity=1&\
mode=async"
```

</CodeGroup>

## Download GTM templates

To learn more about how to track leads with Google Tag Manager, check out the following templates:
Expand Down
Loading