> For the complete documentation index, see [llms.txt](https://docs.getpurpledot.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getpurpledot.com/docs/shopify-stores/pre-order-tracking/google-analytics.md).

# Google Analytics

{% hint style="info" %}
This guide applies only when selling pre-orders through Purple Dot's own checkout. Pre-orders sold through the Shopify checkout benefit from the same tracking as your regular sales.
{% endhint %}

If you have enabled Google Analytics tracking on the Integration settings page in the [Merchant Portal](https://www.purpledotprice.com/merchant-portal/integration), the Purple Dot checkout automatically sends certain events to Google Analytics 4 via the [Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4).

#### **What you need before you start**

* A **Google Analytics 4** property for the store
* The GA4 **Google tag** active on the storefront (for example via the [Google & YouTube](https://apps.shopify.com/google) Shopify app, Google Tag Manager, or a theme tag), with the `_ga` cookie being set for visitors
* Admin (Editor) access to the merchant’s **Google Analytics** property

**Prerequisites**

Before connecting Purple Dot, the GA4 tag must already be running on the Shopify storefront. Purple Dot will not send any server-side events for a session where it cannot find the browser `_ga` cookie that GA4 sets (this is used as the Measurement Protocol `client_id`).

> ***Use the same Measurement ID everywhere.** The Measurement ID you enter in Purple Dot must match the GA4 web data stream already collecting storefront browser events. If these don’t match, connection tests may pass but production checkout events won’t stitch to the correct sessions.*

#### **Step 1 - Install the Google & YouTube app on Shopify**

1. In **Shopify Admin**, go to **Settings → Apps and sales channels** (or open the [Google & YouTube app on the Shopify App Store](https://apps.shopify.com/google)).
2. Install **Google & YouTube** (by Google LLC).
3. Open the app and sign in with the Google account that has access to the merchant’s **Google Analytics** property.
4. Connect the Shopify store to the correct Google account / Analytics property.
5. When prompted, set up or connect a **Google Analytics 4** property and web data stream. Use the same Measurement ID you plan to use for Measurement Protocol and Purple Dot.
6. Complete the app setup and confirm the Google tag is **connected** and **active** on the storefront.

> ***Use the same Measurement ID everywhere.*** *The Measurement ID you enter in Purple Dot must match the GA4 web data stream connected in the Google & YouTube app and shown in Google Analytics. If these don’t match, connection tests may pass but production events will go to the wrong property—or checkout events won’t attribute correctly.*

**Verify the tag is working on the storefront**

1. In **Shopify Admin**, go to **Settings → Customer events**
2. Verify the app is “Connected”
3. On the **Google & YouTube** app, click “Test”

<figure><img src="/files/p2fQo9tey8SUxKanT7TB" alt=""><figcaption></figcaption></figure>

1. Accept any **cookie consent** banner that covers analytics cookies.
2. Confirm events are being processed
3. In GA4, open **Reports → Realtime** and confirm storefront page views are arriving.

#### **Step 2 - Find the Measurement ID and create an API Secret**

**Find the Measurement ID**

1. Open [Google Analytics](https://analytics.google.com/).
2. Go to **Admin → Data streams**.
3. Open the **Web** data stream used on the storefront.
4. Copy the **Measurement ID** (format `G-XXXXXXXX`).

Use this value in Purple Dot’s **Measurement ID** field.

<figure><img src="/files/okUf6UFS5dVe7YIW9UWP" alt=""><figcaption></figcaption></figure>

**Create a Measurement Protocol API Secret**

1. Stay on the same data stream.
2. Open **Measurement Protocol API secrets**.
3. Click **Create**, give it a nickname such as `Purple Dot`, and create the secret.
4. Copy the **Secret value** immediately and store it securely.

This secret is what Purple Dot calls **API Secret**.

You must have **Editor** (or higher) permission on the GA4 property to create API secrets.

<figure><img src="/files/DjbHDC8NBD4oewRVJrrp" alt=""><figcaption></figcaption></figure>

#### **Step 3 - Add credentials in Purple Dot**

1. Log in to the **Purple Dot** [**Merchant Portal**](https://www.purpledotprice.com/merchant-portal/integration).
2. Go to **Settings → Integrations**.
3. Under **Analytics**, click **Connect** for **Google Analytics**.
4. In the Google Analytics connection modal, enter:

   | **Field**          | **Value**                  |
   | ------------------ | -------------------------- |
   | **Measurement ID** | Measurement ID from Step 2 |
   | **API Secret**     | API Secret from Step 2     |
5. Click **Save**.

After the connection is saved, Purple Dot sends real server events automatically when a Google Analytics connection exists for the store.

| Checkout / preorder action | GA4 event name     |
| -------------------------- | ------------------ |
| Add to cart                | `add_to_cart`      |
| Initiate checkout          | `begin_checkout`   |
| Add payment info           | `add_payment_info` |
| Pre-order created          | `purchase`         |

Events include ecommerce fields such as `currency`, `value`, and `items`. Purchase events also include a `transaction_id` (the Purple Dot pre-order / checkout id). When available, Purple Dot also forwards `session_id` (from the `_ga_` session cookie) and Google click identifiers (`gclid` / `gbraid` / `wbraid`) so server events can attribute correctly.

#### **Step 4 - Verify the connection**

There are two ways to verify the integration. Use **Option A** for a quick credential check, **Option B** to test the full checkout flow end-to-end.

**Option A - Test Connection in the modal (recommended for first setup)**

1. In the Google Analytics connection modal, fill in **Measurement ID** and **API Secret**.
2. Click **Test Connection** (bottom-left of the modal).
3. Wait for **“Credentials verified!”**

Purple Dot sends a dedicated validation event to Google’s Measurement Protocol debug endpoint:

* **Event name:** `purple_dot_test`
* **Client ID:** `555.555`

This confirms the Measurement ID and API Secret are accepted by Google. The debug endpoint validates the payload; it is not the same as a storefront checkout event.

**Option B - Test via live checkout (end-to-end)**

This option verifies the full integration: storefront → Purple Dot checkout → GA4 Measurement Protocol → Realtime reporting.

1. Open the storefront and accept cookie consent so the `_ga` cookie is set.
2. In GA4, open **Reports → Realtime** (keep this tab open).
3. Complete a test pre-order/checkout flow (add to cart, open checkout, enter payment details, complete the order).
4. In **Realtime**, confirm the checkout events appear — for example `add_to_cart`, `begin_checkout`, `add_payment_info`, and `purchase`.

> ***Tip:** Server events are only sent when Purple Dot can read a GA4 `client_id` from the storefront `_ga` cookie. If Realtime stays empty after a test checkout, re-check cookie consent and that the Measurement ID in Purple Dot matches the storefront data stream.*