diff --git a/packages/destinations/node/meta/README.md b/packages/destinations/node/meta/README.md index c6eb83be..8c1b6804 100644 --- a/packages/destinations/node/meta/README.md +++ b/packages/destinations/node/meta/README.md @@ -4,6 +4,81 @@

-# Meta destination for walkerOS +# Meta Conversion API (CAPI) destination for walkerOS -[Meta Conversion API](https://developers.facebook.com/docs/marketing-api/conversions-api) (CAPI) +Made to be used with +[node-client](https://www.npmjs.com/package/@elbwalker/client-node) from +[walkerOS](https://github.com/elbwalker/walkerOS). + +More detailed information and examples can be found in the +[documentation](https://www.elbwalker.com/docs/destinations/node/meta). + +## 🤓 Usage + +Start by setting up the config for the destination. Optional fields as comments. +Destinations can be used via node or directly in the browser. + +## Configuration + +Learn more about the +[destinations](https://www.elbwalker.com/docs/destinations/) in general and read +the detailed +[Meta Conversion API](https://developers.facebook.com/docs/marketing-api/conversions-api). + +```js +import type { CustomConfig } from '@elbwalker/destination-node-meta'; + +const config: CustomConfig = { + custom: { + accessToken: 's3cr3tc0d3', + pixelId: '1234567890', + // debug: true, + // partner: 'walkerOS', + // testCode: 'TEST00000', + }, + mapping: { + // e.g. order + entity: { + // e.g. complete + action: { + name: 'Purchase', + custom: { + id: 'data.id', + name: 'data.title', + value: 'data.total', + }, + }, + }, + }, +}; +``` + +### Node usage + +```sh +npm i --save @elbwalker/destination-node-meta +``` + +```ts +import destinationMeta from '@elbwalker/destination-node-meta'; + +elb('walker destination', destinationMeta, config); +``` + +Mapping Mock + +For easier debugging add + +```js +if (response.error) console.log('🚀 ~ response:', response); +``` + +to the `node_modules/facebook-nodejs-business-sdk/dist/cjs` on line 261 within +the `xmlHttpRequest`. + +## Contribute + +Feel free to contribute by submitting an +[issue](https://github.com/elbwalker/walkerOS/issues), starting a +[discussion](https://github.com/elbwalker/walkerOS/discussions) or getting in +[contact](https://calendly.com/elb-alexander/30min). diff --git a/packages/destinations/web/meta-pixel/README.md b/packages/destinations/web/meta-pixel/README.md index 8f0b4fe3..0c920174 100644 --- a/packages/destinations/web/meta-pixel/README.md +++ b/packages/destinations/web/meta-pixel/README.md @@ -16,7 +16,7 @@ Destinations can be used via node or directly in the browser. Learn more about the [destinations](https://www.elbwalker.com/docs/destinations/) in general and read -the detailled +the detailed [Meta Pixel configuration](https://www.elbwalker.com/docs/destinations/web/meta-pixel#configuration). ```js diff --git a/packages/destinations/web/meta-pixel/src/types/index.ts b/packages/destinations/web/meta-pixel/src/types/index.ts index ae57c2f3..7d648b99 100644 --- a/packages/destinations/web/meta-pixel/src/types/index.ts +++ b/packages/destinations/web/meta-pixel/src/types/index.ts @@ -28,6 +28,7 @@ export interface CustomEventConfig { contents?: ParamContents; // Value(s) to be used for contents } +// @TODO use WalkerOS.MappingValue export type PropertyMapping = string | PropertyMappingValue; export interface PropertyMappingValue { diff --git a/packages/types/src/destination.ts b/packages/types/src/destination.ts index 83b218e5..aba35cd9 100644 --- a/packages/types/src/destination.ts +++ b/packages/types/src/destination.ts @@ -40,7 +40,7 @@ export type Meta = { export interface EventConfig { batch?: number; // Bundle events for batch processing batched?: Batch; // Batch of events to be processed - consent?: WalkerOS.Consent; // Required consent states to init and push events + consent?: WalkerOS.Consent; // Required consent states process the event custom?: EventCustom; // Arbitrary but protected configurations for custom event config ignore?: boolean; // Choose to no process an event when set to true name?: string; // Use a custom event name diff --git a/packages/types/src/walkeros.ts b/packages/types/src/walkeros.ts index a23881a5..733d060a 100644 --- a/packages/types/src/walkeros.ts +++ b/packages/types/src/walkeros.ts @@ -185,5 +185,9 @@ export type MappingValue = string | MappingValueObject; export interface MappingValueObject { key?: string; default?: PropertyType; - // consent?: string | Array; + // Ideas: + // - As array to try multiple ways to get the value + // - consent?: string | Array; + // - filter + // - fn } diff --git a/website/docs/destinations/index.mdx b/website/docs/destinations/index.mdx index 1195256f..a18abde0 100644 --- a/website/docs/destinations/index.mdx +++ b/website/docs/destinations/index.mdx @@ -102,20 +102,20 @@ optional. A complete destination configuration might look like this: Overview of all properties: -| Property | Value | Description | -| -------------- | --------- | ------------------------------------------------------------------ | -| **id** | string | A unique key for the destination | -| **consent** | object | Required consent states to init and push events | -| **custom** | any | Used for a destinations individual settings | -| **init** | boolean | If the destination has been initialized by calling the init method | -| **loadScript** | boolean | If an additional script to work should be loaded | -| **mapping** | object | A map to handle events individually | -| **meta** | object | Additional meta information about the destination | -| **queue** | boolean | Disable processing of previously pushed events | -| **verbose** | boolean | Enable verbose logging | -| **onError** | function | Custom error handler | -| **onLog** | function | Custom log handler | -| **on** | On.Config | Rules for on-functions that gets triggered on specific events | +| Property | Value | Description | +| -------------- | --------- | ----------------------------------------------------------------------------------------------------- | +| **id** | string | A unique key for the destination | +| **consent** | object | Required consent states to init and push events | +| **custom** | any | Used for a destinations individual settings | +| **init** | boolean | If the destination has been initialized by calling the init method | +| **loadScript** | boolean | If an additional script to work should be loaded | +| **mapping** | object | Configuration how to transform events (see Mapping) | +| **meta** | object | Additional meta information about the destination | +| **queue** | boolean | Disable processing of previously pushed events | +| **verbose** | boolean | Enable verbose logging | +| **onError** | function | Custom error handler | +| **onLog** | function | Custom log handler | +| **on** | On.Config | Rules for on-functions that gets triggered on specific events | Call `elb('walker destination', { push: console.log }, config);` to add the destination to a client. The destination will log all events straight to the @@ -124,53 +124,6 @@ console. Edit a destinations configuration at runtime by accessing > To grant required consent call `elb('walker consent', { demo: true });`. -## Mapping - -There are common rules for destinations like the renaming of the event name or -the basic rules how to set up the mapping, based on entities and actions -specifically. A `*` can be used to match all entities or actions and set up -common rules. Each destination requires specific settings which can be -configured in the `custom` section of the mapping. - -```js -const mapping = { - entity: { action: {} }, // Basic structure - page: { - view: { name: 'pageview' }, // Rename the event name - click: { custom: { language: 'globals.language' } }, // Custom settings - }, - product: { - visible: { batch: 2000 }, // Bundle all product visible events - }, - // Set custom properties - order: { complete: { name: 'purchase' } }, - '*': { '*': { ignore: true } }, // Ignore all other non-listed events -}; -``` - -The `EventConfig` for each event supports standardized default options. The -`custom` option can be used to set up custom properties for the event and -destinations individual settings. - -| Property | Value | Description | -| ---------- | ------- | ------------------------------------------------------------------------ | -| **batch** | number | Time in ms to bundle the events before calling `pushBatch` if available. | -| **custom** | object | Individual settings for a custom destination. | -| **ignore** | boolean | If set to `true` the event won't get pushed to the destination. | -| **name** | string | Renaming of the event (e.g. product add to add_to_cart) | - -To disable processing events, add `{'*': {'*': { ignore: true }}}` to the -mapping. - -Make sure to not list duplicate keys in the mapping, since this is a n object. - -:::info - -Use Utils/Hooks to modify events before -processing. - -::: - ## Methods A client communicates with a destination through the methods. It's also the diff --git a/website/docs/destinations/mapping.mdx b/website/docs/destinations/mapping.mdx new file mode 100644 index 00000000..3e9bb3a5 --- /dev/null +++ b/website/docs/destinations/mapping.mdx @@ -0,0 +1,56 @@ +--- +title: Mapping +description: How to transform events into another required format. +--- + +import Link from '@docusaurus/Link'; + +The mapping is used to translate events into another required format. It +converts the walkerOS event +model into another format. The mapping also defines how to process +events, like renaming, bundling, or ignoring them. + +There are common rules for destinations like `name` to for renaming an event +(e.g. `product add` to `add_to_cart`) or `ignore` to not process an event at +all. A `*` can be used to match all entities or actions and set up common rules. +Each destination requires specific settings which can be configured in the +`custom` section of the mapping. + +```js +const mapping = { + entity: { action: {} }, // Basic structure + page: { + view: { name: 'pageview' }, // Rename the event name + click: { custom: { language: 'globals.language' } }, // Custom settings + }, + product: { + visible: { batch: 2000 }, // Bundle all product visible events + }, + // Set custom properties + order: { complete: { name: 'purchase' } }, + '*': { '*': { ignore: true } }, // Ignore all other non-listed events +}; +``` + +The `EventConfig` for each event supports standardized default options. The +`custom` option can be used to set up custom properties for the event and +destinations individual settings. + +| Property | Value | Description | +| ---------- | ------- | ------------------------------------------------------------------------ | +| **batch** | number | Time in ms to bundle the events before calling `pushBatch` if available. | +| **custom** | object | Individual settings for a custom destination. | +| **ignore** | boolean | If set to `true` the event won't get pushed to the destination. | +| **name** | string | Renaming of the event (e.g. `product add` to `add_to_cart`) | + +To disable processing events, add `{'*': {'*': { ignore: true }}}` to the +mapping. + +Make sure to not list duplicate keys in the mapping, since this is an object. + +:::info + +Use Utils/Hooks to modify events before +processing. + +::: diff --git a/website/docs/destinations/node/aws.mdx b/website/docs/destinations/node/aws.mdx index 873d87f6..8828504b 100644 --- a/website/docs/destinations/node/aws.mdx +++ b/website/docs/destinations/node/aws.mdx @@ -36,7 +36,7 @@ const config = { firehose: firehoseConfig, }; -elb('walker destination', destinationAWS, config); +await elb('walker destination', destinationAWS, config); ``` ## Firehose @@ -53,7 +53,7 @@ const firehoseConfig = { }, }; -elb('walker destination', destinationAWS, { firehose: firehoseConfig }); +await elb('walker destination', destinationAWS, { firehose: firehoseConfig }); ``` ### Optional Configuration Fields @@ -87,7 +87,7 @@ const config = { }, }; -elb('walker destination', destinationAWS, config); +await elb('walker destination', destinationAWS, config); ``` ## Who this package is for diff --git a/website/docs/destinations/node/bigquery.mdx b/website/docs/destinations/node/bigquery.mdx index 715a85b7..f6d8ab90 100644 --- a/website/docs/destinations/node/bigquery.mdx +++ b/website/docs/destinations/node/bigquery.mdx @@ -32,7 +32,7 @@ destination: ```ts import { destinationBigQuery } from '@elbwalker/destination-node-bigquery'; -elb('walker destination', destinationBigQuery, { +await elb('walker destination', destinationBigQuery, { custom: { projectId: 'PR0J3CT1D', // Required // client: BigQuery; // A BigQuery instance from @google-cloud/bigquery diff --git a/website/docs/destinations/node/meta.mdx b/website/docs/destinations/node/meta.mdx new file mode 100644 index 00000000..c2aea998 --- /dev/null +++ b/website/docs/destinations/node/meta.mdx @@ -0,0 +1,59 @@ +--- +title: Meta Conversion API +description: Meta Conversion API (CAPI) destination for walkerOS +--- + +import Link from '@docusaurus/Link'; +import PackageLink from '/src/components/docs/package-link'; + + + +The Meta +Conversion API (CAPI) destination is used to send server-side events from +walkerOS to the Facebook Conversion API. It handles the data transformation and +ensures that your events are correctly formatted for the Facebook Conversion +API. + +## Basic example + +Here's a simple example to demonstrate how to configure the Meta destination: + +```ts +import { destinationMeta } from '@elbwalker/destination-node-meta'; + +await elb('walker destination', destinationMeta, { + custom: { + accessToken: 's3cr3tc0d3', + pixelId: '1234567890', + // debug: true, + // partner: 'walkerOS', + // testCode: 'TEST00000', + }, + mapping: { + // e.g. order + entity: { + // e.g. complete + action: { + name: 'Purchase', + custom: { + id: 'data.id', + name: 'data.title', + value: 'data.total', + }, + }, + }, + }, +}); +``` + +## Dependencies + +Before using the Meta destination, ensure you have: + +- walkerOS Node client installed +- + Conversion API requirements + diff --git a/website/docs/utils/helper.mdx b/website/docs/utils/helper.mdx index a227ae33..3de06134 100644 --- a/website/docs/utils/helper.mdx +++ b/website/docs/utils/helper.mdx @@ -105,6 +105,15 @@ This function is particularly useful for scenarios where unique identifiers are needed, such as dynamically generated element IDs, unique keys for list items in rendering, or temporary identifiers. +### getMappingValue + +`getMappingValue(event: WalkerOS.Event, mapping: WalkerOS.MappingValue): WalkerOS.Property | undefined` +reads the value from an event based on +the mapping configuration. It +is used by destinations to +transform walkerOS events into +another required format. + ### getMarketingParameters `getMarketingParameters(url: string, custom={}): WalkerOS.Properties` extracts