From 63b5c17ad869a0dd9c65f0ca42b9d2cd06862427 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Wed, 7 Oct 2026 15:41:36 +0700 Subject: [PATCH 1/2] Add docs pages for the Google Analytics 4, Google Tag Manager, Converge, Hotjar and Make apps Each page is written from the app's repo (manifest, README, tracker code, CHANGELOG) in the style of the existing app pages, and added to the Apps sidebar. --- content/docs/apps/converge.mdx | 62 +++++++++++++ content/docs/apps/google-analytics-4.mdx | 81 +++++++++++++++++ content/docs/apps/google-tag-manager.mdx | 108 +++++++++++++++++++++++ content/docs/apps/hotjar.mdx | 40 +++++++++ content/docs/apps/make.mdx | 30 +++++++ content/docs/apps/meta.json | 5 ++ 6 files changed, 326 insertions(+) create mode 100644 content/docs/apps/converge.mdx create mode 100644 content/docs/apps/google-analytics-4.mdx create mode 100644 content/docs/apps/google-tag-manager.mdx create mode 100644 content/docs/apps/hotjar.mdx create mode 100644 content/docs/apps/make.mdx diff --git a/content/docs/apps/converge.mdx b/content/docs/apps/converge.mdx new file mode 100644 index 0000000..99f81bd --- /dev/null +++ b/content/docs/apps/converge.mdx @@ -0,0 +1,62 @@ +--- +title: "Converge" +description: "Send storefront and checkout events to Converge for attribution and conversion tracking" +--- +[Converge](https://www.runconverge.com/) is a marketing attribution and conversion tracking platform. The **Converge** app loads your Converge pixel on your storefront and sends shopping and checkout events, including placed orders, to your Converge event source. + + + +Converge is an installable app. Enable it from the **Apps** menu on your NEXT Dashboard. + + + +The app works with any storefront theme and needs no theme edits. It loads the Converge pixel through the theme's global header app hook and sends events through NEXT's [storefront event tracking](https://developers.nextcommerce.com/docs/storefront/event-tracking), so it covers your storefront and checkout. Pages hosted outside your NEXT storefront, such as external funnels, need their own tracking. + +## Set Up Converge + +1. In Converge, open the event source for your store and copy its pixel code. See Converge's [storefront quickstart](https://docs.runconverge.com/implementation/quickstart#connect-your-storefront). +2. In NEXT, install **Converge** from the **Apps** menu and open its settings. +3. Enter your **Converge Pixel Code**. +4. Tick **Enable Converge Tracking**. +5. Save. + + + +Enter the pixel code before you enable tracking. Events are only sent when both are set. + + + +## Settings + +| Setting | What it does | +| --- | --- | +| **Converge Pixel Code** | The unique pixel code from your Converge event source. | +| **Enable Converge Tracking** | Turns tracking on for your storefront. | +| **Enable Converge Tracking for Test Orders** | Sends [test orders](/docs/manage/orders/test-orders) to Converge as conversions. Off by default, so test orders are not counted. | + +## Tracked Events + +| Storefront activity | Converge event | +| --- | --- | +| Customer views any page | `$page_load` | +| Customer views a product | `Viewed Product` | +| Customer adds a product to the cart | `Added To Cart` | +| Customer starts checkout | `Started Checkout` | +| Customer submits their contact information at checkout | `Added Contact Info` | +| Customer completes an order | `Placed Order` | + +Events follow the [Converge spec](https://docs.runconverge.com/sources/converge-spec). + +### What each event includes + +* **Viewed Product**: product ID, name, URL, price and currency. +* **Added To Cart**: product and variant IDs, SKU, product and variant names, URL, price, currency and quantity. +* **Started Checkout** and **Added Contact Info**: order total, tax, shipping, currency, voucher codes, and the cart's line items (product and variant IDs, SKU, names, price, currency and quantity). +* **Added Contact Info** also sends the customer's email, phone number, and shipping city, state, postcode and country to the Converge profile. +* **Placed Order**: the NEXT order number, plus the same totals, voucher codes and line items. The customer's email, phone number, and billing city, state, postcode and country are sent to the Converge profile. + +### Identity and deduplication + +When a customer submits their contact information, and again when they place an order, the app sends their email address as a Converge alias. This lets Converge connect the customer's earlier anonymous activity to their profile. + +**Placed Order** is sent with an event ID made of your store's identifier and the order number, so each order always carries the same event ID. diff --git a/content/docs/apps/google-analytics-4.mdx b/content/docs/apps/google-analytics-4.mdx new file mode 100644 index 0000000..dd443c8 --- /dev/null +++ b/content/docs/apps/google-analytics-4.mdx @@ -0,0 +1,81 @@ +--- +title: "Google Analytics 4" +description: "Track storefront ecommerce events in GA4, with optional Google Ads conversions" +--- +The **Google Analytics 4** app adds the Google tag to your storefront and sends GA4 ecommerce events, from product views through purchase, to your GA4 property. It can also send a Google Ads conversion when an order is completed. + + + +Google Analytics 4 is an installable app. Enable it from the **Apps** menu on your NEXT Dashboard. + + + +The app works with any storefront theme and needs no theme edits. It loads the Google tag through the theme's global header app hook and sends events through NEXT's [storefront event tracking](https://developers.nextcommerce.com/docs/storefront/event-tracking), so it covers your storefront and checkout. Pages hosted outside your NEXT storefront, such as external funnels, need their own tracking. + +## Set Up Google Analytics 4 + +1. Install **Google Analytics 4** from the **Apps** menu and open its settings. +2. Tick **Enable Google Analytics**. +3. Enter your **Google Analytics Measurement ID**, in the format `G-XXXXXXXXXX`. +4. Save. + + + +The app does nothing until a Measurement ID is set. Ticking **Enable Google Analytics** on its own does not load the Google tag. + + + +## Settings + +| Setting | What it does | +| --- | --- | +| **Enable Google Analytics** | Turns the app on. Nothing loads until a Measurement ID is also set. | +| **Google Analytics Measurement ID** | Your GA4 Measurement ID, `G-XXXXXXXXXX`. | +| **Enable Google Ads Conversion Tracking** | Sends a conversion to Google Ads when an order is completed. Needs the Conversion ID and Conversion Label below. | +| **Google Ads Conversion ID** | Your Google Ads tag ID, for example `AW-123456789`. A number without the `AW-` prefix also works. | +| **Google Ads Conversion Label** | The label from your Google Ads conversion action. | +| **Enable Debug Mode** | Sends events in debug mode, so they appear in GA4 **DebugView** in real time. | +| **Skip Test Orders** | Does not send `purchase` or the Google Ads conversion for [test orders](/docs/manage/orders/test-orders). | + +## Tracked Events + +The app sends these GA4 recommended ecommerce events: + +| Storefront activity | GA4 event | +| --- | --- | +| Customer views a category or collection page | `view_item_list` | +| Customer views a product | `view_item` | +| Customer adds a product to the cart | `add_to_cart` | +| Customer removes a product from the cart | `remove_from_cart` | +| Customer starts checkout | `begin_checkout` | +| Customer submits a shipping method | `add_shipping_info` | +| Customer completes an order | `purchase` | + +The Google tag sends `page_view` on every page load. If a customer is signed in to their storefront account, their customer ID is sent to GA4 as the `user_id`. + +### Values and Items + +* Every money value is sent as a number in the order's currency. +* `value` on `begin_checkout`, `add_shipping_info` and `purchase` is item revenue: the sum of the line prices excluding tax. Shipping and tax are sent separately in the `shipping` and `tax` parameters. +* `transaction_id` on `purchase` is the NEXT order number. +* Items use the same identifiers on every event, so GA4 item reports join across the funnel: `item_id` is the product ID, and `sku` and `item_variant` identify the variant. +* The first voucher applied to the cart or order is sent as `coupon`. +* `view_item_list` uses the page path as the list ID and the page title as the list name. GA4 accepts up to 200 items per event, so longer lists are cut to the first 200. + +## Google Ads Conversions + +With **Enable Google Ads Conversion Tracking** on and both a Conversion ID and Conversion Label set, the app sends a Google Ads `conversion` on every completed order, alongside the GA4 `purchase` event. The conversion carries the order number as the transaction ID, and the order total, including shipping and tax, as its value. + +If the Conversion ID or Conversion Label is missing or not in the format Google Ads issues, no conversion is sent. + + + +To send your product catalog to Google Merchant Center for Google Ads, see [Google Merchant XML Feed](/docs/build-a-store/catalogue/google-merchant-xml-feed). + + + +## Good to Know + +* Every GA4 event is addressed to the Measurement ID in the app settings. If another Google tag is on the page, it does not receive these events. +* If your theme, or a tag in Google Tag Manager, already loads the Google tag for the same Measurement ID, remove it so page views are not counted twice. +* Use **Enable Debug Mode** with GA4 **DebugView** to check events while testing, then turn it off. diff --git a/content/docs/apps/google-tag-manager.mdx b/content/docs/apps/google-tag-manager.mdx new file mode 100644 index 0000000..3184a17 --- /dev/null +++ b/content/docs/apps/google-tag-manager.mdx @@ -0,0 +1,108 @@ +--- +title: "Google Tag Manager" +description: "Load your GTM container on your storefront and push GA4-style ecommerce events to the dataLayer" +--- +The **Google Tag Manager** app loads your Google Tag Manager (GTM) container on your storefront and pushes ecommerce events to the `dataLayer`, from product views through purchase. Tags in your container can then forward those events to GA4, Google Ads, or any other destination. + + + +Google Tag Manager is an installable app. Enable it from the **Apps** menu on your NEXT Dashboard. + + + +The app works with any storefront theme and needs no theme edits. It loads the container through the theme's global header app hook and pushes events through NEXT's [storefront event tracking](https://developers.nextcommerce.com/docs/storefront/event-tracking), so it covers your storefront and checkout. Pages hosted outside your NEXT storefront, such as external funnels, need their own tracking. + + + +If you only need GA4, the [Google Analytics 4](/docs/apps/google-analytics-4) app sends the same events straight to GA4 without a container to manage. + + + +## Set Up Google Tag Manager + +1. Install **Google Tag Manager** from the **Apps** menu and open its settings. +2. Tick **Enable Google Tag Manager**. +3. Enter your **Google Tag Manager Container ID**, in the format `GTM-XXXXXXX`. +4. Save. +5. In GTM, add triggers and tags for the events listed below, then publish your container. + + + +The app does nothing until a Container ID is set. Ticking **Enable Google Tag Manager** on its own does not load the container. + + + +## Settings + +| Setting | What it does | +| --- | --- | +| **Enable Google Tag Manager** | Turns the app on. Nothing loads until a Container ID is also set. | +| **Google Tag Manager Container ID** | Your GTM Container ID, `GTM-XXXXXXX`. | +| **Skip Test Orders** | Does not push the `purchase` event for [test orders](/docs/manage/orders/test-orders). | + +## Events Pushed to the dataLayer + +Event names and payloads follow the GA4 ecommerce format, so a GA4 event tag in GTM can use them as they are. + +| Storefront activity | dataLayer event | +| --- | --- | +| Customer views any page | `page_view` | +| Customer views a category or collection page | `view_item_list` | +| Customer views a product | `view_item` | +| Customer adds a product to the cart | `add_to_cart` | +| Customer removes a product from the cart | `remove_from_cart` | +| Customer starts checkout | `begin_checkout` | +| Customer submits a shipping method | `add_shipping_info` | +| Customer completes an order | `purchase` | + +Every push also includes `page_location`, `page_path`, `page_title` and `page_referrer`. Before each ecommerce push, the app pushes `{ ecommerce: null }` to clear the previous ecommerce object, as Google recommends. + + + +The `page_view` push is there for container triggers. The Google tag inside your container already sends its own page view, so don't attach a GA4 event tag to this push. + + + +### Example purchase push + +```js +{ + event: "purchase", + page_location: "https://example.com/checkout/...", + page_path: "/checkout/...", + page_title: "Checkout", + page_referrer: "https://example.com/cart/", + ecommerce: { + transaction_id: "100123", // NEXT order number + currency: "USD", + value: 79.98, // item revenue, excluding tax + shipping: 5.00, + tax: 6.40, + coupon: "WELCOME10", // first voucher, when one is applied + items: [ + { + item_id: "42", // product ID + item_name: "Example Product", + sku: "EX-42-BLK", + item_variant: "Black", + price: 39.99, // per unit, excluding tax + discount: 0, + quantity: 2, + index: 0 + } + ] + } +} +``` + +### Values and Items + +* Every money value is a number in the order's currency. +* `value` on `begin_checkout`, `add_shipping_info` and `purchase` is item revenue: the sum of the line prices excluding tax. Shipping and tax are sent separately. +* `add_shipping_info` includes the chosen shipping method as `shipping_tier`. +* Items use the same identifiers on every event: `item_id` is the product ID, and `sku` and `item_variant` identify the variant. +* `view_item_list` uses the page path as the list ID and the page title as the list name. GA4 accepts up to 200 items per event, so longer lists are cut to the first 200. + +## Troubleshooting + +If the browser console shows `[Google Tag Manager app] dataLayer was missing on the storefront page`, the container did not load before the first event. This usually means your theme does not render the global header app hook. Events are still queued in the `dataLayer`, but the container itself will not load until the hook is present. Custom themes should include the [app hooks](https://developers.nextcommerce.com/docs/apps/snippets) in their base layout. diff --git a/content/docs/apps/hotjar.mdx b/content/docs/apps/hotjar.mdx new file mode 100644 index 0000000..aa18c92 --- /dev/null +++ b/content/docs/apps/hotjar.mdx @@ -0,0 +1,40 @@ +--- +title: "Hotjar" +description: "Add Hotjar heatmaps and session recordings to your storefront" +--- +[Hotjar](https://www.hotjar.com/) shows how customers use your store with heatmaps and session recordings. The **Hotjar** app adds your Hotjar tracking code to every storefront page, so you can see the full customer journey through to checkout. + + + +Hotjar is an installable app. Enable it from the **Apps** menu on your NEXT Dashboard. + + + +The app works with any storefront theme and needs no theme edits. It loads the Hotjar tracking code through the theme's global header app hook, which also renders on checkout. Pages hosted outside your NEXT storefront, such as external funnels, need their own Hotjar installation. + +## Set Up Hotjar + +1. In Hotjar, open the installation instructions for your site and copy your **Site ID**. +2. In NEXT, install **Hotjar** from the **Apps** menu and open its settings. +3. Enter your **Hotjar Site ID**. +4. Tick **Enable Hotjar Tracking**. +5. Save, then open your storefront and confirm in Hotjar that data is arriving. + + + +Enter the Site ID before you enable tracking. If tracking is enabled with no Site ID, the Hotjar code cannot load. + + + +## Settings + +| Setting | What it does | +| --- | --- | +| **Enable Hotjar Tracking** | Adds the Hotjar tracking code to your storefront. | +| **Hotjar Site ID** | The Site ID from your Hotjar account's installation instructions. | + +## Good to Know + +* The app installs the Hotjar tracking code only. It does not send NEXT ecommerce events or customer details to Hotjar. +* Because the code loads on checkout pages too, review your Hotjar data suppression settings before you enable recordings. +* If your theme already includes the Hotjar tracking code, remove it so Hotjar is not loaded twice. diff --git a/content/docs/apps/make.mdx b/content/docs/apps/make.mdx new file mode 100644 index 0000000..9b53941 --- /dev/null +++ b/content/docs/apps/make.mdx @@ -0,0 +1,30 @@ +--- +title: "Make" +description: "Automate workflows between your NEXT store and hundreds of other apps with Make" +--- +[Make](https://www.make.com/) is a visual automation platform. NEXT's app on Make lets you build scenarios that connect your store to hundreds of other services, so you can automate workflows across your tools without writing code. + + + +The NEXT integration is installed from Make, not from the NEXT **Apps** menu. You need a [Make account](https://www.make.com/en/register?pc=next29) and access to your NEXT store's Dashboard. + + + +## Connect Make to Your Store + +1. In Make, open the [NEXT integration](https://www.make.com/en/integrations/twentyninenext) and add a NEXT module to a scenario. +2. When Make asks for a connection, create a new one. Make sends you to your NEXT store to approve the connection. +3. Review the permissions Make requests and authorize the app in your store's Dashboard. +4. You're returned to Make, and the connection is ready to use in your scenarios. + +The connection uses OAuth, the same authorization flow as other apps on the [NEXT App Framework](https://developers.nextcommerce.com/docs/apps/oauth). Make never sees your Dashboard password, and the access it holds is limited to the permissions you approved. + +## Build Scenarios + +The modules available for NEXT, and the triggers and actions each one offers, are listed on the [NEXT integration page](https://www.make.com/en/integrations/twentyninenext) on Make. Scenarios run on Make, so scenario history, errors and operation usage are all in your Make account. + + + +To send store events to Make or any other service without a dedicated module, create a [webhook](/docs/build-a-store/technical-settings/configure-webhooks) in your store and point it at a Make **Custom webhook** trigger. + + diff --git a/content/docs/apps/meta.json b/content/docs/apps/meta.json index b629249..f7b6909 100644 --- a/content/docs/apps/meta.json +++ b/content/docs/apps/meta.json @@ -4,10 +4,15 @@ "3pl-central", "avalara-avatax", "campaigns-app", + "converge", "delivery-tracking", "everflow", + "google-analytics-4", + "google-tag-manager", "gorgias", + "hotjar", "klaviyo", + "make", "meta-pixel", "midigator", "shipstation", From a5c6cfd9eac62f12acd7a11cc168571672fac56f Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Wed, 7 Oct 2026 16:00:44 +0700 Subject: [PATCH 2/2] Converge and Hotjar: note tax in Converge prices, sharpen the empty Site ID warning --- content/docs/apps/converge.mdx | 6 ++++++ content/docs/apps/hotjar.mdx | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/content/docs/apps/converge.mdx b/content/docs/apps/converge.mdx index 99f81bd..e32c6f5 100644 --- a/content/docs/apps/converge.mdx +++ b/content/docs/apps/converge.mdx @@ -55,6 +55,12 @@ Events follow the [Converge spec](https://docs.runconverge.com/sources/converge- * **Added Contact Info** also sends the customer's email, phone number, and shipping city, state, postcode and country to the Converge profile. * **Placed Order**: the NEXT order number, plus the same totals, voucher codes and line items. The customer's email, phone number, and billing city, state, postcode and country are sent to the Converge profile. + + +The **Added To Cart** price excludes tax. Line item prices on **Started Checkout**, **Added Contact Info** and **Placed Order** include tax, and the order total includes tax and shipping. Keep this in mind when you compare Converge revenue with NEXT order reports. + + + ### Identity and deduplication When a customer submits their contact information, and again when they place an order, the app sends their email address as a Converge alias. This lets Converge connect the customer's earlier anonymous activity to their profile. diff --git a/content/docs/apps/hotjar.mdx b/content/docs/apps/hotjar.mdx index aa18c92..b3d5c00 100644 --- a/content/docs/apps/hotjar.mdx +++ b/content/docs/apps/hotjar.mdx @@ -22,7 +22,7 @@ The app works with any storefront theme and needs no theme edits. It loads the H -Enter the Site ID before you enable tracking. If tracking is enabled with no Site ID, the Hotjar code cannot load. +Save a valid Site ID before you enable tracking. If tracking is enabled with an empty Site ID, the Hotjar code fails with a JavaScript error on every storefront page and Hotjar does not load.