diff --git a/content/docs/campaigns/configuration.mdx b/content/docs/campaigns/configuration.mdx index e7af4cda..989812e0 100644 --- a/content/docs/campaigns/configuration.mdx +++ b/content/docs/campaigns/configuration.mdx @@ -6,7 +6,7 @@ import { Callout } from 'fumadocs-ui/components/callout'; The SDK is configured via `window.nextConfig` before the SDK script loads, and via meta tags in your HTML ``. -Replace `your-api-key-here` with your actual Campaign API key from the dashboard. +Replace `your-api-key-here` with your actual Campaign API key from the dashboard. If you're using [campaign-page-kit](https://github.com/NextCommerceCo/next-campaign-page-kit), run `npm run config` to set the API key interactively. ## JavaScript Configuration @@ -14,12 +14,9 @@ Replace `your-api-key-here` with your actual Campaign API key from the dashboard ### Minimal Setup ```javascript -// Configure before SDK loads -window.dataLayer = window.dataLayer || []; -window.nextReady = window.nextReady || []; - window.nextConfig = { - apiKey: "your-api-key-here" + apiKey: "your-api-key-here", + storeName: "your-store-name", }; ``` @@ -30,6 +27,9 @@ window.nextConfig = { // Required: Your Campaign Cart API key apiKey: "your-api-key-here", + // Required for Facebook purchase deduplication + storeName: "your-store-name", + // Currency behavior when country changes currencyBehavior: 'auto', // 'auto' | 'manual' @@ -45,17 +45,22 @@ window.nextConfig = { // Address and country configuration addressConfig: { + // Low-priority fallback when the campaign API returns no country list defaultCountry: "US", - showCountries: ["US", "CA", "GB", "AU", "DE", "FR"], + // Deprecated — the campaign API now provides the country list. Use as a fallback only. + // showCountries: ["US", "CA", "GB", "AU", "DE", "FR"], dontShowStates: ["AS", "GU", "PR", "VI"], - enableAutocomplete: true, // NEXT Address Autocomplete + // Address autocomplete — choose one: + // Option 1 (NextCommerce): enableAutocomplete: true, leave googleMaps.apiKey empty + // Option 2 (Google Maps): set googleMaps.apiKey below — takes priority when non-empty + // Option 3 (Disabled): remove enableAutocomplete and leave googleMaps.apiKey empty + enableAutocomplete: true, }, - // Google Maps integration (address autocomplete) + // Google Maps API key — leave empty to use NextCommerce autocomplete googleMaps: { - apiKey: "your-google-maps-api-key", + apiKey: "", region: "US", - enableAutocomplete: false }, // Analytics providers @@ -70,7 +75,6 @@ window.nextConfig = { enabled: false, settings: { containerId: "GTM-XXXXXX", - dataLayerName: "dataLayer" }, }, facebook: { @@ -97,16 +101,24 @@ window.nextConfig = { utmTransfer: { enabled: true, applyToExternalLinks: false, - debug: false, - // Optional: excludedDomains: ['example.com'], - // Optional: paramsToCopy: ['utm_source', 'utm_medium', 'utm_campaign', 'gclid', 'fbclid'] - } + }, + + // Optional: discount/promo codes + // discounts: { + // SAVE10: { code: 'SAVE10', type: 'percentage', value: 10, scope: 'order' } + // }, + + // Optional: profiles for dynamic package mapping (e.g. exit intent pricing) + // profiles: { + // SAVE_5: { name: 'Exit Save 5', packageMappings: { 1: 9, 2: 10 } } + // }, }; ``` + ## Meta Tag Configuration -Configure the SDK on a per-page basis using meta tags in your HTML ``: +Configure the SDK on a per-page basis using meta tags in your HTML ``. If you're using campaign-page-kit, these are set automatically from page frontmatter via `base.html`. ```html @@ -121,7 +133,7 @@ Configure the SDK on a per-page basis using meta tags in your HTML ``: - + diff --git a/content/docs/campaigns/index.mdx b/content/docs/campaigns/index.mdx index f6861b21..d7ef8e91 100644 --- a/content/docs/campaigns/index.mdx +++ b/content/docs/campaigns/index.mdx @@ -56,11 +56,11 @@ Campaign responses include `available_payment_methods` and `available_express_pa A **package** is a virtual link to a **product variant** (SKU) in your store catalog with a custom quantity and custom pricing. Packages are what customers actually purchase in a campaign — they let you create different purchasing options for the same product without changing the product itself. -For example, a single product could have multiple packages offering different quantities at different price points: +In SDK 0.4.x, the recommended pattern is **one package with a base price**, using **Campaign Offers** to define quantity-tier discounts automatically. For example: -- **1x Widget** — 1 unit at $10.00 -- **3x Widget Bundle** — 3 units at $7.00 each ($21.00 total) -- **5x Widget Best Value** — 5 units at $6.00 each ($30.00 total) +- **1x Widget** — 1 unit at base price +- **2x Widget** — 2 units, 20% off via Campaign Offer +- **3x Widget** — 3 units, 35% off via Campaign Offer Packages can also be configured as **recurring** for subscription products, with a custom interval (e.g. every 30 days). @@ -96,47 +96,82 @@ There are two ways to build your campaign frontend: | Approach | Best For | Description | | --- | --- | --- | -| [**Campaign Cart SDK**](/docs/campaigns/cart-system) | Fastest development | An attribute-driven HTML/JS SDK. Build cart, checkout, and upsell flows using `data-next-*` attributes — no custom JavaScript required. | -| [**Campaigns API**](/docs/campaigns/api) | Full control | A headless REST API for developers who want complete control over the checkout experience with custom JavaScript. | +| [**Campaign Cart SDK**](/docs/campaigns/cart-system) | Full control | A headless SDK driven by `data-next-*` HTML attributes. Build cart, checkout, and upsell flows without writing custom cart logic. | +| [**Campaigns API**](/docs/campaigns/api) | Custom integrations | A headless REST API for developers who want complete control over the checkout experience with custom JavaScript. | - -The fastest way to get started is with the [Campaign Cart Starter Template](https://github.com/NextCommerceCo/campaign-cart-example) — a ready-to-use campaign flow with landing page, checkout, upsell, and receipt pages pre-configured. + +The fastest way to get started is with the [Campaign Cart Starter Templates](https://github.com/NextCommerceCo/campaign-cart-starter-templates) — a collection of ready-to-use campaign templates (checkout, upsell, receipt) built on [next-campaign-page-kit](https://github.com/NextCommerceCo/next-campaign-page-kit), the official build tool for Campaign Cart projects. ## Quick Start -### Option 1: Use Starter Template (Recommended) +### Option 1: Use Starter Templates (Recommended) -Get started quickly with our pre-configured starter template: +The starter templates use [next-campaign-page-kit](https://github.com/NextCommerceCo/next-campaign-page-kit) — a build tool that handles Liquid templating, per-campaign asset isolation, a dev server, and CLI scripts. -**[Download Starter Template](https://github.com/NextCommerceCo/campaign-cart-example)** — Clone or download a ready-to-use campaign flow (landing → checkout → upsell → receipt) with Campaign Cart integrated. +```bash +git clone https://github.com/NextCommerceCo/campaign-cart-starter-templates.git +cd campaign-cart-starter-templates +npm install +npm run dev +``` + +Select a campaign from the interactive prompt. Available templates include single-step checkouts (`demeter`, `limos`, `olympus`), multi-variant flows, and shop-style variants. + +
+ + Olympus checkout template preview +
+
Olympus
+
Single-step checkout — Preview →
+
+ + + Olympus MV checkout template preview +
+
Olympus MV
+
Single-step with multi-variant support — Preview →
+
+ +
### Option 2: Manual Setup +For standalone HTML pages without the campaign-page-kit build tool: + 1. **Get Your API Key** - Go to Next Commerce Dashboard, open the Campaigns app, select your campaign, click on Integration, and copy your API key. + Go to Next Commerce Dashboard, open the Campaigns App, select your campaign, click on Integration, and copy your API key. 2. **Add SDK Script** Add these two lines to your HTML `` section: ```html - + - - - + + ``` - - Check the [GitHub releases](https://github.com/NextCommerceCo/campaign-cart/releases) for the latest stable version. For development, you can use `@latest`, but we recommend pinning to a specific version (e.g., `@v0.3.10`) in production for stability. + + Always pin to a specific version (e.g. `@v0.4.18`). Check [GitHub releases](https://github.com/NextCommerceCo/campaign-cart/releases) for the latest stable version. Using `@latest` in production can cause unexpected behaviour when the SDK updates. -3. **Start Building** +3. **Configure the SDK** + + Set `window.nextConfig` before the SDK loads. See [Configuration](/docs/campaigns/configuration) for the full reference. - You can now use Campaign Cart attributes in your HTML! + ```javascript + window.nextConfig = { + apiKey: "your-api-key-here", + }; + ``` + +4. **Start Building** + + You can now use Campaign Cart attributes in your HTML. ## HTML Page Setup @@ -144,26 +179,18 @@ Get started quickly with our pre-configured starter template: - - - window.nextConfig = { - apiKey: "your-api-key-here", - }; - - - + - + - + - - - + + @@ -173,23 +200,39 @@ Get started quickly with our pre-configured starter template: ## Quick Examples +### Bundle Selector (0.4.x — recommended) + +Uses one package with Campaign Offers driving tier pricing automatically: + +```html +
+
+ 1x — +
+
+ 2x — Save + +
+
+ 3x — +
+
+``` + ### Add to Cart Button ```html ``` -### Product Selector -```html -
-
Option 1
-
Option 2
-
-``` - ### Display Cart Total ```html $0.00 @@ -211,7 +254,6 @@ console.log(window.next ? 'SDK Loaded' : 'SDK Not Found'); if (window.next) { console.log('SDK Version:', next.version); - console.log('Config:', next.getConfig()); } ``` diff --git a/public/assets/campaigns/template-olympus-mv.png b/public/assets/campaigns/template-olympus-mv.png new file mode 100644 index 00000000..6fb6c6d7 Binary files /dev/null and b/public/assets/campaigns/template-olympus-mv.png differ diff --git a/public/assets/campaigns/template-olympus.png b/public/assets/campaigns/template-olympus.png new file mode 100644 index 00000000..2092a804 Binary files /dev/null and b/public/assets/campaigns/template-olympus.png differ