@uptain-gmbh/uptain-pwa

@uptain-gmbh/uptain-pwa

Uptain tracking and personalization module for PlentyONE / Plentyshop PWA (Nuxt 3).

Install the package, register the module, set environment variables — no patches to Plentyshop core files (settings.config.ts, settings-groups-imports, etc.) are required.

Requirements

• Plentyshop PWA / PlentyONE project (Nuxt 3)
• @plentymarkets/shop-api and @plentymarkets/shop-core (peer dependencies)
• A working shop .env with PlentyONE API credentials (API_ENDPOINT, API_SECURITY_TOKEN, CONFIG_ID, …) — see the Plentyshop quickstart

Installation

Standard (inside apps/web)

cd apps/web
npm install @uptain-gmbh/uptain-pwa@1.0.6

Turborepo / monorepo (from repository root)

npm install @uptain-gmbh/uptain-pwa@1.0.6 --workspace=web
# or
cd apps/web && npm install @uptain-gmbh/uptain-pwa@1.0.6

Setup (manual steps after install)

1. Register the Nuxt module

In apps/web/nuxt.config.ts:

export default defineNuxtConfig({
  modules: [
    '@plentymarkets/shop-core',
    '@plentymarkets/shop-module-mollie',
    '@plentymarkets/shop-module-gtag',
    '@uptain-gmbh/uptain-pwa',
    // ...other modules
  ],
});

2. Environment variables

Copy the Uptain keys from this package’s .env.example into your shop apps/web/.env.

Minimum example:

# Required when tracking is enabled
NUXT_PUBLIC_UPTAIN_ID=YOUR_TRACKING_ID
NUXT_PUBLIC_UPTAIN_ENABLED=1

# Optional
NUXT_PUBLIC_UPTAIN_DEBUG_MODE=0
NUXT_PUBLIC_UPTAIN_COOKIE_GROUP=CookieBar.marketing.label
NUXT_PUBLIC_UPTAIN_CONSENT_MANAGER_VENDOR_ID=
NUXT_PUBLIC_UPTAIN_BLOCK_COOKIES_INITIALLY=false
NUXT_PUBLIC_UPTAIN_TRANSMIT_NEWSLETTER_DATA=false
NUXT_PUBLIC_UPTAIN_TRANSMIT_CUSTOMER_DATA=false
NUXT_PUBLIC_UPTAIN_TRANSMIT_REVENUE=false

Shop credentials (API_ENDPOINT, API_SECURITY_TOKEN, CONFIG_ID, …) are not part of this package — configure them in the shop .env as usual for Plentyshop.

The module merges the Uptain keys into runtimeConfig.public automatically. You do not need to edit apps/web/app/configuration/settings.config.ts.

3. Ignore generated files

The module creates a symlink at build time:

apps/web/modules/uptain/runtime → node_modules/@uptain-gmbh/uptain-pwa/runtime

Add to your shop .gitignore:

# Uptain PWA module (generated on nuxt prepare / dev / build)
apps/web/modules/uptain

4. Restart the dev server

After install or .env changes:

npm run dev

The editor settings symlink is created when Nuxt starts (nuxt prepare / npm run dev).

5. Editor settings (merchant UI)

Merchants configure Uptain under:

SEO settings → Tracking & analytics → Uptain

Local development (editor UI)

In apps/web/.env (shop side — not published by this package):

NUXT_PUBLIC_IS_PREVIEW=1

Restart the dev server and open the shop in the browser.

Optional: if preview mode is driven by a PlentyONE cookie in your environment, set a pwa cookie and reload. This is not required on all setups.

Production / PlentyONE preview

1. Deploy the shop from your Git connection in PlentyONE.
2. Activate preview mode for the shop.
3. Open the editor from PlentyONE (Shop » Management).

Changes to some editor settings may require a shop redeploy to take effect (shown in the Uptain settings panel).

What you do not need to change

On stock Plentyshop PWA:

• apps/web/app/utils/settings-groups-imports — no extra globs
• apps/web/app/utils/settings-translations-imports — no extra globs
• apps/web/app/configuration/settings.config.ts — no Uptain keys required

The module registers editor UI via apps/web/modules/uptain/runtime, which Plentyshop discovers with its built-in ~~/modules/*/runtime/components/settings/** glob.

How it works (technical)

1. Tracking: client/server plugins load the Uptain script and register cookie-bar entries.
2. Editor UI: on module setup, runtime/ is linked into apps/web/modules/uptain/runtime.
3. Settings API: useSiteSettings('uptainId') etc. read from runtimeConfig.public and persisted shop settings.

Troubleshooting

Enable debug logging:

NUXT_PUBLIC_UPTAIN_DEBUG_MODE=1

License

MIT