@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

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 and waits for the amboras_consent cookie to grant analytics (re-checked on amboras-consent-changed). Only then does it set the Consent Mode v2 signals, load the AW- tag once (DOM-idempotent), enable Enhanced Conversions, and stash {conversionId, labels, enhancedConversions} on window.__amborasGoogleAds. Before consent no gtag, dataLayer or AW- script exists on the page.
• 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.
• The tag and all conversions are gated on amboras_consent.analytics. Nothing loads or fires until it is true: an absent cookie (no banner shown yet, or no click) counts as denied. The Amboras edge writes a granted cookie automatically for shoppers outside the EEA, UK and Switzerland. Once the tag loads, the 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,
})