-# 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