@amboras-dev/google-ads

Google Ads conversion tracking for Amboras storefronts — the Amboras equivalent of the "Google Ads Pixel by Nabu" Shopify app. Fully client-side via Google's tag (gtag.js): conversion tracking, Enhanced Conversions, Consent Mode v2, deterministic dedup, and accurate multi-currency conversion values.

Install

pnpm add @amboras-dev/google-ads

What's tracked

| Stage | Event | Slot | Class | | --- | --- | --- | --- | | Load tag + Consent Mode | page_view | rootProviders | A (GoogleAdsProvider) | | Product view | view_item | pdpAnalytics | A (GoogleAdsViewItem) | | Add to cart | add_to_cart | cartUpdate | B (tracker template) | | Begin checkout | begin_checkout | checkoutStart | B (tracker template) | | Purchase | purchase | checkoutComplete | B (tracker template) |

Each conversion fires gtag('event', 'conversion', { send_to: 'AW-XXXX/<label>', value, currency, transaction_id, items }). The conversion id and per-action conversion labels come from the merchant's admin settings, served by GET /store/google-ads/config.

Architecture

• GoogleAdsProvider (Class A, rootProviders) — self-fetches config, sets Consent Mode v2 from the amboras_consent cookie (updates live on amboras-consent-changed), loads the AW- tag once (DOM-idempotent), enables Enhanced Conversions, and stashes {conversionId, labels, enhancedConversions} on window.__amborasGoogleAds.
• GoogleAdsViewItem (Class A, pdpAnalytics) — fires view_item.
• Class B trackers (add-to-cart / begin-checkout / purchase) read real cart.items / order line items + customer email/phone from local React scope, so values and item ids are correct (the slot context alone only exposes {cartId,itemCount,total,currency}).

Multi-currency

Every event carries the buyer's real currency_code and a value scaled by that currency's own decimal count via toMajorUnits(amount, currency) (Intl-based) — not a blind /100. JPY/KRW (0-decimal) and KWD/BHD (3-decimal) are correct.

Enhanced Conversions & consent

• First-party data (email, phone_number) is forwarded raw to gtag('set','user_data',…); Google's tag normalises + SHA-256 hashes it client-side. Nothing sensitive leaves the browser unhashed and no server relay is involved.
• All conversions are gated on amboras_consent.analytics, and Consent Mode v2 signals (ad_storage, ad_user_data, ad_personalization, analytics_storage) mirror that consent.

Programmatic API

import { trackPurchase, cartItemsToItems } from '@amboras-dev/google-ads'

trackPurchase({
  orderId: order.id,
  items: cartItemsToItems(order.items, order.currency_code),
  totalMinor: order.total, // minor units; converted per-currency
  currency: order.currency_code,
  email: order.email,
})