diff --git a/docs/content/scripts/tracking/snapchat-pixel.md b/docs/content/scripts/tracking/snapchat-pixel.md new file mode 100644 index 00000000..38ad3be3 --- /dev/null +++ b/docs/content/scripts/tracking/snapchat-pixel.md @@ -0,0 +1,207 @@ +--- +title: Snapchat Pixel +description: Use Snapchat Pixel in your Nuxt app. +links: +- label: Source + icon: i-simple-icons-github + to: https://github.com/nuxt/scripts/blob/main/src/runtime/registry/snapchat-pixel.ts + size: xs +--- + +[Snapchat Pixel](https://businesshelp.snapchat.com/s/article/snap-pixel-about){:target="_blank"} lets you measure the crossdevice impact for your Snapchat ad campaigns. + +Nuxt Scripts provides a registry script composable `useScriptSnapchatPixel` to easily integrate Snapchat Pixel in your Nuxt app. + +### Nuxt Config Setup + +The simplest way to load Snpachat Pixel globally in your Nuxt App is to use Nuxt config. Alternatively you can directly +use the [useScriptSnapchatPixel](#useScriptSnapchatPixel) composable. + +If you don't plan to send custom events you can use the [Environment overrides](https://nuxt.com/docs/getting-started/configuration#environment-overrides) to +disable the script in development. + +::code-group + +```ts [Always enabled] +export default defineNuxtConfig({ + scripts: { + registry: { + snapchatPixel: { + id: 'YOUR_ID' + } + } + } +}) +``` + +```ts [Production only] +export default defineNuxtConfig({ + $production: { + scripts: { + registry: { + snapchatPixel: { + id: 'YOUR_ID', + } + } + } + } +}) +``` + +:: + +#### With Environment Variables + +If you prefer to configure your id using environment variables. + +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + scripts: { + registry: { + snapchatPixel: true, + } + }, + // you need to provide a runtime config to access the environment variables + runtimeConfig: { + public: { + scripts: { + snapchatPixel: { + id: '', // NUXT_PUBLIC_SCRIPTS_SNAPCHAT_PIXEL_ID + }, + }, + }, + }, +}) +``` + +```text [.env] +NUXT_PUBLIC_SCRIPTS_SNAPCHAT_PIXEL_ID= +``` + +## useScriptSnapchatPixel + +The `useScriptSnapchatPixel` composable lets you have fine-grain control over when and how Snapchat Pixel is loaded on your site. + +```ts +const { proxy } = useScriptSnapchatPixel({ + id: 'YOUR_ID', + user_email: 'USER_EMAIL' +}) +// example +proxy.snaptr('track', 'PURCHASE', { + currency: 'USD', + price: 120.10, + transaction_id: '11111' +}) +``` + +Please follow the [Registry Scripts](/docs/guides/registry-scripts) guide to learn more about advanced usage. + +### SnapchatPixelApi + +```ts +export interface SnapPixelApi { + snaptr: SnapTrFns & { + push: SnapTrFns + loaded: boolean + version: string + queue: any[] + } + _snaptr: SnapPixelApi['snaptr'] + handleRequest?: SnapTrFns +} +type StandardEvents = 'PAGE_VIEW' | 'VIEW_CONTENT' | 'ADD_CART' | 'SIGN_UP' | 'SAVE' | 'START_CHECKOUT' | 'APP_OPEN' | 'ADD_BILLING' | 'SEARCH' | 'SUBSCRIBE' | 'AD_CLICK' | 'AD_VIEW' | 'COMPLETE_TUTORIAL' | 'LEVEL_COMPLETE' | 'INVITE' | 'LOGIN' | 'SHARE' | 'RESERVE' | 'ACHIEVEMENT_UNLOCKED' | 'ADD_TO_WISHLIST' | 'SPENT_CREDITS' | 'RATE' | 'START_TRIAL' | 'LIST_VIEW' +type SnapTrFns = + ((event: 'track', eventName: StandardEvents | '', data?: EventObjectProperties) => void) & + ((event: 'init', id: string, data?: Record) => void) & + ((event: 'init', id: string, data?: InitObjectProperties) => void) & + ((event: string, ...params: any[]) => void) +interface EventObjectProperties { + price?: number + client_dedup_id?: string + currency?: string + transaction_id?: string + item_ids?: string[] + item_category?: string + description?: string + search_string?: string + number_items?: number + payment_info_available?: 0 | 1 + sign_up_method?: string + success?: 0 | 1 + brands?: string[] + delivery_method?: 'in_store' | 'curbside' | 'delivery' + customer_status?: 'new' | 'returning' | 'reactivated' + event_tag?: string + [key: string]: any +} +interface InitObjectProperties { + user_email?: string + ip_address?: string + user_phone_number?: string + user_hashed_email?: string + user_hashed_phone_number?: string + firstname?: string + lastname?: string + geo_city?: string + geo_region?: string + geo_postal_code?: string + geo_country?: string + age?: string +} +``` + +### Config Schema + +You must provide the options when setting up the script for the first time. + +```ts +export const SnapTrPixelOptions = object({ + id: string(), + trackPageView: optional(boolean()), + user_email: optional(string()), + ip_address: optional(string()), + user_phone_number: optional(string()), + user_hashed_email: optional(string()), + user_hashed_phone_number: optional(string()), + firstname: optional(string()), + lastname: optional(string()), + geo_city: optional(string()), + geo_region: optional(string()), + geo_postal_code: optional(string()), + geo_country: optional(string()), + age: optional(string()), +}) +``` + +## Example + +Using Snapchat Pixel only in production while using `snaptr` to send a conversion event. + +::code-group + +```vue [ConversionButton.vue] + + + +``` + +:: diff --git a/playground/pages/index.vue b/playground/pages/index.vue index 18dbd0b0..b1583695 100644 --- a/playground/pages/index.vue +++ b/playground/pages/index.vue @@ -58,6 +58,10 @@ const thirdParties = [ name: 'Segment', path: '/third-parties/segment', }, + { + name: 'Snapchat', + path: '/third-parties/snapchat/nuxt-scripts', + }, ] const thirdPartyComponents = [ diff --git a/playground/pages/third-parties/snapchat/default.vue b/playground/pages/third-parties/snapchat/default.vue new file mode 100644 index 00000000..58c69959 --- /dev/null +++ b/playground/pages/third-parties/snapchat/default.vue @@ -0,0 +1,27 @@ + + + diff --git a/playground/pages/third-parties/snapchat/nuxt-scripts.vue b/playground/pages/third-parties/snapchat/nuxt-scripts.vue new file mode 100644 index 00000000..23ada1ca --- /dev/null +++ b/playground/pages/third-parties/snapchat/nuxt-scripts.vue @@ -0,0 +1,28 @@ + + + diff --git a/src/registry.ts b/src/registry.ts index 16ebea4d..2ba58115 100644 --- a/src/registry.ts +++ b/src/registry.ts @@ -96,6 +96,16 @@ export const registry: (resolve?: (s: string) => string) => RegistryScripts = (r from: resolve('./runtime/registry/x-pixel'), }, }, + { + label: 'Snapchat Pixel', + src: 'https://sc-static.net/scevent.min.js', + category: 'tracking', + logo: '', + import: { + name: 'useScriptSnapchatPixel', + from: resolve('./runtime/registry/snapchat-pixel'), + }, + }, // ads { label: 'Google Adsense', diff --git a/src/runtime/registry/snapchat-pixel.ts b/src/runtime/registry/snapchat-pixel.ts new file mode 100644 index 00000000..857af99f --- /dev/null +++ b/src/runtime/registry/snapchat-pixel.ts @@ -0,0 +1,111 @@ +import { useRegistryScript } from '../utils' +import type { InferInput } from '#nuxt-scripts-validator' +import { boolean, object, optional, string } from '#nuxt-scripts-validator' +import type { RegistryScriptInput } from '#nuxt-scripts/types' + +type StandardEvents = 'PAGE_VIEW' | 'VIEW_CONTENT' | 'ADD_CART' | 'SIGN_UP' | 'SAVE' | 'START_CHECKOUT' | 'APP_OPEN' | 'ADD_BILLING' | 'SEARCH' | 'SUBSCRIBE' | 'AD_CLICK' | 'AD_VIEW' | 'COMPLETE_TUTORIAL' | 'LEVEL_COMPLETE' | 'INVITE' | 'LOGIN' | 'SHARE' | 'RESERVE' | 'ACHIEVEMENT_UNLOCKED' | 'ADD_TO_WISHLIST' | 'SPENT_CREDITS' | 'RATE' | 'START_TRIAL' | 'LIST_VIEW' + +interface EventObjectProperties { + price?: number + client_dedup_id?: string + currency?: string + transaction_id?: string + item_ids?: string[] + item_category?: string + description?: string + search_string?: string + number_items?: number + payment_info_available?: 0 | 1 + sign_up_method?: string + success?: 0 | 1 + brands?: string[] + delivery_method?: 'in_store' | 'curbside' | 'delivery' + customer_status?: 'new' | 'returning' | 'reactivated' + event_tag?: string + [key: string]: any +} + +export const InitObjectPropertiesSchema = object({ + user_email: optional(string()), + ip_address: optional(string()), + user_phone_number: optional(string()), + user_hashed_email: optional(string()), + user_hashed_phone_number: optional(string()), + firstname: optional(string()), + lastname: optional(string()), + geo_city: optional(string()), + geo_region: optional(string()), + geo_postal_code: optional(string()), + geo_country: optional(string()), + age: optional(string()), +}) + +type InitObjectProperties = InferInput + +type SnapTrFns = + ((event: 'track', eventName: StandardEvents | '', data?: EventObjectProperties) => void) & + ((event: 'init', id: string, data?: Record) => void) & + ((event: 'init', id: string, data?: InitObjectProperties) => void) & + ((event: string, ...params: any[]) => void) + +export interface SnapPixelApi { + snaptr: SnapTrFns & { + push: SnapTrFns + loaded: boolean + version: string + queue: any[] + } + _snaptr: SnapPixelApi['snaptr'] + handleRequest?: SnapTrFns +} + +declare global { + interface Window extends SnapPixelApi {} +} + +export const SnapTrPixelOptions = object({ + id: string(), + trackPageView: optional(boolean()), + ...InitObjectPropertiesSchema.entries, +}) +export type SnapTrPixelInput = RegistryScriptInput + +export function useScriptSnapchatPixel(_options?: SnapTrPixelInput) { + return useRegistryScript('snapchatPixel', options => ({ + scriptInput: { + src: 'https://sc-static.net/scevent.min.js', + crossorigin: false, + }, + schema: import.meta.dev ? SnapTrPixelOptions : undefined, + scriptOptions: { + use() { + return { snaptr: window.snaptr } + }, + }, + clientInit: import.meta.server + ? undefined + : () => { + const snaptr: SnapPixelApi['snaptr'] = window.snaptr = function (...params: any[]) { + // @ts-expect-error untypeds + if (snaptr.handleRequest) { + // @ts-expect-error untyped + snaptr.handleRequest(...params) + } + else { + snaptr.queue.push(params) + } + } as any as SnapPixelApi['snaptr'] + if (!window.snaptr) + window._snaptr = snaptr + snaptr.push = snaptr + snaptr.loaded = true + snaptr.version = '1.0' + snaptr.queue = [] + const { id, ...initData } = options + snaptr('init', options?.id, initData) + if (options?.trackPageView) { + snaptr('track', 'PAGE_VIEW') + } + }, + }), _options) +} diff --git a/src/runtime/types.ts b/src/runtime/types.ts index 148691c4..a21d4bd5 100644 --- a/src/runtime/types.ts +++ b/src/runtime/types.ts @@ -20,6 +20,7 @@ import type { MatomoAnalyticsInput } from './registry/matomo-analytics' import type { StripeInput } from './registry/stripe' import type { VimeoPlayerInput } from './registry/vimeo-player' import type { XPixelInput } from './registry/x-pixel' +import type { SnapTrPixelInput } from './registry/snapchat-pixel' import type { YouTubePlayerInput } from './registry/youtube-player' import type { PlausibleAnalyticsInput } from './registry/plausible-analytics' import type { NpmInput } from './registry/npm' @@ -152,6 +153,7 @@ export interface ScriptRegistry { segment?: SegmentInput stripe?: StripeInput xPixel?: XPixelInput + snapchatPixel?: SnapTrPixelInput youtubePlayer?: YouTubePlayerInput vimeoPlayer?: VimeoPlayerInput [key: `${string}-npm`]: NpmInput