From 541c0516b2df8eb0680eda607cbe7ccda8becd73 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Fri, 29 Sep 2023 10:26:32 +0200 Subject: [PATCH 01/13] Content and Product configuration added --- docs/cdp/cdp_content_activation.md | 205 ++++++++++++++++++++++++++++ docs/cdp/cdp_product_activation.md | 206 +++++++++++++++++++++++++++++ docs/cdp/cdp_user_activation.md | 200 ++++++++++++++++++++++++++++ 3 files changed, 611 insertions(+) create mode 100644 docs/cdp/cdp_content_activation.md create mode 100644 docs/cdp/cdp_product_activation.md create mode 100644 docs/cdp/cdp_user_activation.md diff --git a/docs/cdp/cdp_content_activation.md b/docs/cdp/cdp_content_activation.md new file mode 100644 index 0000000000..6eac30d276 --- /dev/null +++ b/docs/cdp/cdp_content_activation.md @@ -0,0 +1,205 @@ +--- +description: Step-by-step activation procedure of Ibexa CDP. +--- + +# CDP activation + +## Configuration + +To configure Ibexa CDP, use the `ibexa.system..cdp` [configuration key](configuration.md#configuration-files): + +```yaml +ibexa_cdp: + data_export: + schedule: + content: + # You can use examples below to build your own data export schedule. + # Accepted options can be listed by running `php bin/console ibexa:cdp:stream-content-data --help` + # every 30 minutes + - + interval: '*/30 * * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --content-type=article --no-draft' +​ + # every 12 hours + - + interval: '0 */12 * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --content-type=article --no-draft' +``` + +All configuration settings are described below. +You can follow them step by step to set up your Ibexa CDP. + +### Segment group + +First, create a segment group in the Back Office. +It will serve as a container for all segments data generated by Ibexa CDP. +Go to **Admin** -> **Segments** and select **Create**. +Fill in name and identifier for a segment group. +Choose wisely, as once connected to CDP Segment Group cannot be changed. + +![Creating a new segment group](img/cdp_create_segment_group.png) + +Next, add a segment group identifier to the configuration. + +!!! caution "Ibexa CDP Segment Group" + + After you create the Segment Group in the Back Office and connect it to Ibexa CDP, you cannot change it in any way, including edit its name. + +## Account number + +Now, fill in the account number. +Log in to Ibexa CDP and in the top right corner, select available accounts. + +![List of available accounts](img/cdp_accounts.png) + +A pop-up window displays with a list of all available accounts and their numbers. + +![Account number](img/cdp_account_number.png) + +## Data export + +You need to specify a source of the user data that Ibexa CDP will connect to. +To do so, go to **Data Manager** in **Tools** section and select **Create new dataflow**. +It will take you to a Dataflow Creator, where in five steps you will set up a data streaming. + +### General Information + +In the **General Information** section, specify dataflow name, +choose **Stream File** as a source of user data and **CDP** as a destination, +where they will be sent for processing. +Currently, only Stream File transport is supported and can be initialized from the configuration. + +### Download + +In the **Download** section, select **Stream file**. +Copy generated steam ID and paste it into the configuration file under `stream_id`. +It allows you to establish a datastream from the Streaming API into the Data Manager. + +Next, you need to export your user data to the CDP. +Go to your installation and use this command: + +```bash +php bin/console ibexa:cdp:stream-user-data --draft +``` + +There are two versions of this command `--draft/--no-draft`. +The first one is used to send the test user data to the Data Manager. +If it passes a validation test in the **Activation** section, use the latter one to send a full version. + +Next, go back to Ibexa CDP and select **Validate & download**. +If the file passes, you will see a confirmation message. +Now, you can go to the **File mapping** section. + +### File mapping + +Mapping is completed automatically, the system fills all required information and shows available columns with datapoints on the right. +You can change their names if needed or disallow empty fields by checking **Mandatory**. +If the provided file contains empty values, this option is not available. + +If provided file is not recognized, the system will require you to fill in the parsing-options manually or select an appropriate format. +If you make any alterations, select the **Parse File** to generate columns with new data. + +### Transform & Map + +In the **Transform & Map** section you transform data and map it to a schema. +At this point, you can map **email** to **email** and **id** to **integer** fields to get custom columns. + +Next, select **Create schema based on the downloaded columns**. +It will move you to Schema Creator. +There, choose **PersonalData** as a parent and name the schema. + +![Create new schema](img/cdp_create_new_schema.png) + +Next, select all the columns and set Person Identifier as **userid**. + +![Person Identifier](img/cdp_person_identifier.png) + +If you used PersonData or Catalog type schemas, the system will require +specifying the Write Mode that will be applied to them. + +**Append** (default one) allows new data to overwrite the old one but leaves existing entries unaffected. +All entries are stored in the dataset, unchanged by updating dataflow. +For example, if a customer unsubscribes a newsletter, their email will remain in the system. +**Overwrite** completely removes the original dataset and replaces it with the new one every time the dataflow runs. + +Next, select **userid** from a **Schema columns section** on the right and map it to **id**. + +![Map userid to id](img/cdp_userid_mapid.png) + +### Activation + +In this section you will test the dataflow with provided test user data. +If everything passes, go to your installation and export production data with this command: + +```bash +php bin/console ibexa:cdp:stream-user-data --no-draft +``` + +Now you can run and activate the dataflow. + +### Build new Audience/Segment + +Go to the **Audience Builder** and select **Build new audience**. +When naming the audience remember, you will need to find it in a drop-down list during activation. +There, you can choose conditions from `did`, `did not` or `have`. +The conditions `did` and `did not` allow you to use events like buy, visit or add to a cart from online tracking. +- `have` conditions are tied to personal characteristics and can be used to track the sum of all buys or top-visited categories. + +In the Audience Builder, you can also connect created audiences to the activations. + +## Activation + +Activation synchronises data from Ibexa CDP to the Ibexa DXP. +When you specify a segment, you can activate it on multiple communication channels, such as newsletters or commercials. +You can configure multiple activations based data flows. + +First, from the menu bar, select **Activations** and create a new **Ibexa** activation. +Specify name of your activation, select `userid` as **Person Identifier** and click **Next**. + +![General Information - Activation](img/cdp_activation_general_info.png) + +Next, you can fill in **Ibexa information** they must match the ones provided in the YAML configuration: + +- **Client Secret** and **Client ID** - are used to authenticate against Webhook endpoint. In the configuration they are taken from environment variables in `.env` file. + +- **Segment Group Identifier** - identifier of the segment group in Ibexa DXP. It points to a segment group where all the CDP audiences will be stored. +- **Base URL** - URL of your instance with added `/cdp/webhook` at the end. + +![Ibexa Information - Activation](img/cdp_activation_ibexa_info.png) + +Finally, you can specify the audiences you wish to include. + +!!! note "CDP requests" + + All CDP requests are logged in with `debug` severity. + +## Add Client-side Tracking + +The final step is setting up a tracking script. +It requires a head tracking script between the `` tags on your website +and a main script after the head script, and cookie consent. +You can do it by following [tutorial in the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/115000656909-Client-side-Tracking). + +Now, you need to add a tracker to specific places in your website where you want to track users. +For example, add this tracker to the Landing Page template if you want to track user entrances. + +```js +raptor.trackEvent('visit', ..., ...); +``` +or buys: + +```js + //Parameters for Product 1 +raptor.trackEvent('buy', ..., ...); + //Parameters for Product 2 +raptor.trackEvent('buy', ..., ...); +``` + +For tracing to be effective, you also need to send ID of a logged-in user in the same way. +Add the user ID information by using below script: + +```js +raptor.push("setRuid","USER_ID_HERE") +``` + +For more information on tracking events, see [the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/201912411-Tracking-Events). diff --git a/docs/cdp/cdp_product_activation.md b/docs/cdp/cdp_product_activation.md new file mode 100644 index 0000000000..d6084c3d91 --- /dev/null +++ b/docs/cdp/cdp_product_activation.md @@ -0,0 +1,206 @@ +--- +description: Step-by-step activation procedure of Ibexa CDP. +--- + +# CDP activation + +## Configuration + +To configure Ibexa CDP, use the `ibexa.system..cdp` [configuration key](configuration.md#configuration-files): + +```yaml +ibexa_cdp: + data_export: + schedule: + product: + # You can use examples below to build your own data export schedule. + # Accepted options can be listed by running `php bin/console ibexa:cdp:stream-product-data --help` + # every 30 minutes + - + interval: '*/30 * * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --product-type=computer --no-draft' +​ + # every 12 hours + - + interval: '0 */12 * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --product-type=computer --no-draft' +​ +``` + +All configuration settings are described below. +You can follow them step by step to set up your Ibexa CDP. + +### Segment group + +First, create a segment group in the Back Office. +It will serve as a container for all segments data generated by Ibexa CDP. +Go to **Admin** -> **Segments** and select **Create**. +Fill in name and identifier for a segment group. +Choose wisely, as once connected to CDP Segment Group cannot be changed. + +![Creating a new segment group](img/cdp_create_segment_group.png) + +Next, add a segment group identifier to the configuration. + +!!! caution "Ibexa CDP Segment Group" + + After you create the Segment Group in the Back Office and connect it to Ibexa CDP, you cannot change it in any way, including edit its name. + +## Account number + +Now, fill in the account number. +Log in to Ibexa CDP and in the top right corner, select available accounts. + +![List of available accounts](img/cdp_accounts.png) + +A pop-up window displays with a list of all available accounts and their numbers. + +![Account number](img/cdp_account_number.png) + +## Data export + +You need to specify a source of the user data that Ibexa CDP will connect to. +To do so, go to **Data Manager** in **Tools** section and select **Create new dataflow**. +It will take you to a Dataflow Creator, where in five steps you will set up a data streaming. + +### General Information + +In the **General Information** section, specify dataflow name, +choose **Stream File** as a source of user data and **CDP** as a destination, +where they will be sent for processing. +Currently, only Stream File transport is supported and can be initialized from the configuration. + +### Download + +In the **Download** section, select **Stream file**. +Copy generated steam ID and paste it into the configuration file under `stream_id`. +It allows you to establish a datastream from the Streaming API into the Data Manager. + +Next, you need to export your user data to the CDP. +Go to your installation and use this command: + +```bash +php bin/console ibexa:cdp:stream-user-data --draft +``` + +There are two versions of this command `--draft/--no-draft`. +The first one is used to send the test user data to the Data Manager. +If it passes a validation test in the **Activation** section, use the latter one to send a full version. + +Next, go back to Ibexa CDP and select **Validate & download**. +If the file passes, you will see a confirmation message. +Now, you can go to the **File mapping** section. + +### File mapping + +Mapping is completed automatically, the system fills all required information and shows available columns with datapoints on the right. +You can change their names if needed or disallow empty fields by checking **Mandatory**. +If the provided file contains empty values, this option is not available. + +If provided file is not recognized, the system will require you to fill in the parsing-options manually or select an appropriate format. +If you make any alterations, select the **Parse File** to generate columns with new data. + +### Transform & Map + +In the **Transform & Map** section you transform data and map it to a schema. +At this point, you can map **email** to **email** and **id** to **integer** fields to get custom columns. + +Next, select **Create schema based on the downloaded columns**. +It will move you to Schema Creator. +There, choose **PersonalData** as a parent and name the schema. + +![Create new schema](img/cdp_create_new_schema.png) + +Next, select all the columns and set Person Identifier as **userid**. + +![Person Identifier](img/cdp_person_identifier.png) + +If you used PersonData or Catalog type schemas, the system will require +specifying the Write Mode that will be applied to them. + +**Append** (default one) allows new data to overwrite the old one but leaves existing entries unaffected. +All entries are stored in the dataset, unchanged by updating dataflow. +For example, if a customer unsubscribes a newsletter, their email will remain in the system. +**Overwrite** completely removes the original dataset and replaces it with the new one every time the dataflow runs. + +Next, select **userid** from a **Schema columns section** on the right and map it to **id**. + +![Map userid to id](img/cdp_userid_mapid.png) + +### Activation + +In this section you will test the dataflow with provided test user data. +If everything passes, go to your installation and export production data with this command: + +```bash +php bin/console ibexa:cdp:stream-user-data --no-draft +``` + +Now you can run and activate the dataflow. + +### Build new Audience/Segment + +Go to the **Audience Builder** and select **Build new audience**. +When naming the audience remember, you will need to find it in a drop-down list during activation. +There, you can choose conditions from `did`, `did not` or `have`. +The conditions `did` and `did not` allow you to use events like buy, visit or add to a cart from online tracking. +- `have` conditions are tied to personal characteristics and can be used to track the sum of all buys or top-visited categories. + +In the Audience Builder, you can also connect created audiences to the activations. + +## Activation + +Activation synchronises data from Ibexa CDP to the Ibexa DXP. +When you specify a segment, you can activate it on multiple communication channels, such as newsletters or commercials. +You can configure multiple activations based data flows. + +First, from the menu bar, select **Activations** and create a new **Ibexa** activation. +Specify name of your activation, select `userid` as **Person Identifier** and click **Next**. + +![General Information - Activation](img/cdp_activation_general_info.png) + +Next, you can fill in **Ibexa information** they must match the ones provided in the YAML configuration: + +- **Client Secret** and **Client ID** - are used to authenticate against Webhook endpoint. In the configuration they are taken from environment variables in `.env` file. + +- **Segment Group Identifier** - identifier of the segment group in Ibexa DXP. It points to a segment group where all the CDP audiences will be stored. +- **Base URL** - URL of your instance with added `/cdp/webhook` at the end. + +![Ibexa Information - Activation](img/cdp_activation_ibexa_info.png) + +Finally, you can specify the audiences you wish to include. + +!!! note "CDP requests" + + All CDP requests are logged in with `debug` severity. + +## Add Client-side Tracking + +The final step is setting up a tracking script. +It requires a head tracking script between the `` tags on your website +and a main script after the head script, and cookie consent. +You can do it by following [tutorial in the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/115000656909-Client-side-Tracking). + +Now, you need to add a tracker to specific places in your website where you want to track users. +For example, add this tracker to the Landing Page template if you want to track user entrances. + +```js +raptor.trackEvent('visit', ..., ...); +``` +or buys: + +```js + //Parameters for Product 1 +raptor.trackEvent('buy', ..., ...); + //Parameters for Product 2 +raptor.trackEvent('buy', ..., ...); +``` + +For tracing to be effective, you also need to send ID of a logged-in user in the same way. +Add the user ID information by using below script: + +```js +raptor.push("setRuid","USER_ID_HERE") +``` + +For more information on tracking events, see [the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/201912411-Tracking-Events). diff --git a/docs/cdp/cdp_user_activation.md b/docs/cdp/cdp_user_activation.md new file mode 100644 index 0000000000..6bd428b901 --- /dev/null +++ b/docs/cdp/cdp_user_activation.md @@ -0,0 +1,200 @@ +--- +description: Step-by-step activation procedure of Ibexa CDP. +--- + +# CDP activation + +## Configuration + +To configure Ibexa CDP, use the `ibexa.system..cdp` [configuration key](configuration.md#configuration-files): + +```yaml +ibexa_cdp: + data_export: + schedule: + user: + # You can use examples below to build your own data export schedule. + # Accepted options can be listed by running `php bin/console ibexa:cdp:stream-user-data --help` + # every 15 minutes + - + interval: '*/15 * * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --user-content-type=user --no-draft' +``` + +All configuration settings are described below. +You can follow them step by step to set up your Ibexa CDP. + +### Segment group + +First, create a segment group in the Back Office. +It will serve as a container for all segments data generated by Ibexa CDP. +Go to **Admin** -> **Segments** and select **Create**. +Fill in name and identifier for a segment group. +Choose wisely, as once connected to CDP Segment Group cannot be changed. + +![Creating a new segment group](img/cdp_create_segment_group.png) + +Next, add a segment group identifier to the configuration. + +!!! caution "Ibexa CDP Segment Group" + + After you create the Segment Group in the Back Office and connect it to Ibexa CDP, you cannot change it in any way, including edit its name. + +## Account number + +Now, fill in the account number. +Log in to Ibexa CDP and in the top right corner, select available accounts. + +![List of available accounts](img/cdp_accounts.png) + +A pop-up window displays with a list of all available accounts and their numbers. + +![Account number](img/cdp_account_number.png) + +## Data export + +You need to specify a source of the user data that Ibexa CDP will connect to. +To do so, go to **Data Manager** in **Tools** section and select **Create new dataflow**. +It will take you to a Dataflow Creator, where in five steps you will set up a data streaming. + +### General Information + +In the **General Information** section, specify dataflow name, +choose **Stream File** as a source of user data and **CDP** as a destination, +where they will be sent for processing. +Currently, only Stream File transport is supported and can be initialized from the configuration. + +### Download + +In the **Download** section, select **Stream file**. +Copy generated steam ID and paste it into the configuration file under `stream_id`. +It allows you to establish a datastream from the Streaming API into the Data Manager. + +Next, you need to export your user data to the CDP. +Go to your installation and use this command: + +```bash +php bin/console ibexa:cdp:stream-user-data --draft +``` + +There are two versions of this command `--draft/--no-draft`. +The first one is used to send the test user data to the Data Manager. +If it passes a validation test in the **Activation** section, use the latter one to send a full version. + +Next, go back to Ibexa CDP and select **Validate & download**. +If the file passes, you will see a confirmation message. +Now, you can go to the **File mapping** section. + +### File mapping + +Mapping is completed automatically, the system fills all required information and shows available columns with datapoints on the right. +You can change their names if needed or disallow empty fields by checking **Mandatory**. +If the provided file contains empty values, this option is not available. + +If provided file is not recognized, the system will require you to fill in the parsing-options manually or select an appropriate format. +If you make any alterations, select the **Parse File** to generate columns with new data. + +### Transform & Map + +In the **Transform & Map** section you transform data and map it to a schema. +At this point, you can map **email** to **email** and **id** to **integer** fields to get custom columns. + +Next, select **Create schema based on the downloaded columns**. +It will move you to Schema Creator. +There, choose **PersonalData** as a parent and name the schema. + +![Create new schema](img/cdp_create_new_schema.png) + +Next, select all the columns and set Person Identifier as **userid**. + +![Person Identifier](img/cdp_person_identifier.png) + +If you used PersonData or Catalog type schemas, the system will require +specifying the Write Mode that will be applied to them. + +**Append** (default one) allows new data to overwrite the old one but leaves existing entries unaffected. +All entries are stored in the dataset, unchanged by updating dataflow. +For example, if a customer unsubscribes a newsletter, their email will remain in the system. +**Overwrite** completely removes the original dataset and replaces it with the new one every time the dataflow runs. + +Next, select **userid** from a **Schema columns section** on the right and map it to **id**. + +![Map userid to id](img/cdp_userid_mapid.png) + +### Activation + +In this section you will test the dataflow with provided test user data. +If everything passes, go to your installation and export production data with this command: + +```bash +php bin/console ibexa:cdp:stream-user-data --no-draft +``` + +Now you can run and activate the dataflow. + +### Build new Audience/Segment + +Go to the **Audience Builder** and select **Build new audience**. +When naming the audience remember, you will need to find it in a drop-down list during activation. +There, you can choose conditions from `did`, `did not` or `have`. +The conditions `did` and `did not` allow you to use events like buy, visit or add to a cart from online tracking. +- `have` conditions are tied to personal characteristics and can be used to track the sum of all buys or top-visited categories. + +In the Audience Builder, you can also connect created audiences to the activations. + +## Activation + +Activation synchronises data from Ibexa CDP to the Ibexa DXP. +When you specify a segment, you can activate it on multiple communication channels, such as newsletters or commercials. +You can configure multiple activations based data flows. + +First, from the menu bar, select **Activations** and create a new **Ibexa** activation. +Specify name of your activation, select `userid` as **Person Identifier** and click **Next**. + +![General Information - Activation](img/cdp_activation_general_info.png) + +Next, you can fill in **Ibexa information** they must match the ones provided in the YAML configuration: + +- **Client Secret** and **Client ID** - are used to authenticate against Webhook endpoint. In the configuration they are taken from environment variables in `.env` file. + +- **Segment Group Identifier** - identifier of the segment group in Ibexa DXP. It points to a segment group where all the CDP audiences will be stored. +- **Base URL** - URL of your instance with added `/cdp/webhook` at the end. + +![Ibexa Information - Activation](img/cdp_activation_ibexa_info.png) + +Finally, you can specify the audiences you wish to include. + +!!! note "CDP requests" + + All CDP requests are logged in with `debug` severity. + +## Add Client-side Tracking + +The final step is setting up a tracking script. +It requires a head tracking script between the `` tags on your website +and a main script after the head script, and cookie consent. +You can do it by following [tutorial in the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/115000656909-Client-side-Tracking). + +Now, you need to add a tracker to specific places in your website where you want to track users. +For example, add this tracker to the Landing Page template if you want to track user entrances. + +```js +raptor.trackEvent('visit', ..., ...); +``` +or buys: + +```js + //Parameters for Product 1 +raptor.trackEvent('buy', ..., ...); + //Parameters for Product 2 +raptor.trackEvent('buy', ..., ...); +``` + +For tracing to be effective, you also need to send ID of a logged-in user in the same way. +Add the user ID information by using below script: + +```js +raptor.push("setRuid","USER_ID_HERE") +``` + +For more information on tracking events, see [the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/201912411-Tracking-Events). From 86bf866ed07e4504c7d3eb8a780a1c8a39ed6ac7 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Fri, 6 Oct 2023 09:49:03 +0200 Subject: [PATCH 02/13] CDP global configuration and data export pages added --- docs/cdp/cdp_content_activation.md | 205 -------------------------- docs/cdp/cdp_data_export.md | 86 +++++++++++ docs/cdp/cdp_global_configuration.md | 59 ++++++++ docs/cdp/cdp_product_activation.md | 206 --------------------------- docs/cdp/cdp_user_activation.md | 200 -------------------------- 5 files changed, 145 insertions(+), 611 deletions(-) delete mode 100644 docs/cdp/cdp_content_activation.md create mode 100644 docs/cdp/cdp_data_export.md create mode 100644 docs/cdp/cdp_global_configuration.md delete mode 100644 docs/cdp/cdp_product_activation.md delete mode 100644 docs/cdp/cdp_user_activation.md diff --git a/docs/cdp/cdp_content_activation.md b/docs/cdp/cdp_content_activation.md deleted file mode 100644 index 6eac30d276..0000000000 --- a/docs/cdp/cdp_content_activation.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -description: Step-by-step activation procedure of Ibexa CDP. ---- - -# CDP activation - -## Configuration - -To configure Ibexa CDP, use the `ibexa.system..cdp` [configuration key](configuration.md#configuration-files): - -```yaml -ibexa_cdp: - data_export: - schedule: - content: - # You can use examples below to build your own data export schedule. - # Accepted options can be listed by running `php bin/console ibexa:cdp:stream-content-data --help` - # every 30 minutes - - - interval: '*/30 * * * *' - options: '--stream-id=00000000-00000000-00000000-00000000 --content-type=article --no-draft' -​ - # every 12 hours - - - interval: '0 */12 * * *' - options: '--stream-id=00000000-00000000-00000000-00000000 --content-type=article --no-draft' -``` - -All configuration settings are described below. -You can follow them step by step to set up your Ibexa CDP. - -### Segment group - -First, create a segment group in the Back Office. -It will serve as a container for all segments data generated by Ibexa CDP. -Go to **Admin** -> **Segments** and select **Create**. -Fill in name and identifier for a segment group. -Choose wisely, as once connected to CDP Segment Group cannot be changed. - -![Creating a new segment group](img/cdp_create_segment_group.png) - -Next, add a segment group identifier to the configuration. - -!!! caution "Ibexa CDP Segment Group" - - After you create the Segment Group in the Back Office and connect it to Ibexa CDP, you cannot change it in any way, including edit its name. - -## Account number - -Now, fill in the account number. -Log in to Ibexa CDP and in the top right corner, select available accounts. - -![List of available accounts](img/cdp_accounts.png) - -A pop-up window displays with a list of all available accounts and their numbers. - -![Account number](img/cdp_account_number.png) - -## Data export - -You need to specify a source of the user data that Ibexa CDP will connect to. -To do so, go to **Data Manager** in **Tools** section and select **Create new dataflow**. -It will take you to a Dataflow Creator, where in five steps you will set up a data streaming. - -### General Information - -In the **General Information** section, specify dataflow name, -choose **Stream File** as a source of user data and **CDP** as a destination, -where they will be sent for processing. -Currently, only Stream File transport is supported and can be initialized from the configuration. - -### Download - -In the **Download** section, select **Stream file**. -Copy generated steam ID and paste it into the configuration file under `stream_id`. -It allows you to establish a datastream from the Streaming API into the Data Manager. - -Next, you need to export your user data to the CDP. -Go to your installation and use this command: - -```bash -php bin/console ibexa:cdp:stream-user-data --draft -``` - -There are two versions of this command `--draft/--no-draft`. -The first one is used to send the test user data to the Data Manager. -If it passes a validation test in the **Activation** section, use the latter one to send a full version. - -Next, go back to Ibexa CDP and select **Validate & download**. -If the file passes, you will see a confirmation message. -Now, you can go to the **File mapping** section. - -### File mapping - -Mapping is completed automatically, the system fills all required information and shows available columns with datapoints on the right. -You can change their names if needed or disallow empty fields by checking **Mandatory**. -If the provided file contains empty values, this option is not available. - -If provided file is not recognized, the system will require you to fill in the parsing-options manually or select an appropriate format. -If you make any alterations, select the **Parse File** to generate columns with new data. - -### Transform & Map - -In the **Transform & Map** section you transform data and map it to a schema. -At this point, you can map **email** to **email** and **id** to **integer** fields to get custom columns. - -Next, select **Create schema based on the downloaded columns**. -It will move you to Schema Creator. -There, choose **PersonalData** as a parent and name the schema. - -![Create new schema](img/cdp_create_new_schema.png) - -Next, select all the columns and set Person Identifier as **userid**. - -![Person Identifier](img/cdp_person_identifier.png) - -If you used PersonData or Catalog type schemas, the system will require -specifying the Write Mode that will be applied to them. - -**Append** (default one) allows new data to overwrite the old one but leaves existing entries unaffected. -All entries are stored in the dataset, unchanged by updating dataflow. -For example, if a customer unsubscribes a newsletter, their email will remain in the system. -**Overwrite** completely removes the original dataset and replaces it with the new one every time the dataflow runs. - -Next, select **userid** from a **Schema columns section** on the right and map it to **id**. - -![Map userid to id](img/cdp_userid_mapid.png) - -### Activation - -In this section you will test the dataflow with provided test user data. -If everything passes, go to your installation and export production data with this command: - -```bash -php bin/console ibexa:cdp:stream-user-data --no-draft -``` - -Now you can run and activate the dataflow. - -### Build new Audience/Segment - -Go to the **Audience Builder** and select **Build new audience**. -When naming the audience remember, you will need to find it in a drop-down list during activation. -There, you can choose conditions from `did`, `did not` or `have`. -The conditions `did` and `did not` allow you to use events like buy, visit or add to a cart from online tracking. -- `have` conditions are tied to personal characteristics and can be used to track the sum of all buys or top-visited categories. - -In the Audience Builder, you can also connect created audiences to the activations. - -## Activation - -Activation synchronises data from Ibexa CDP to the Ibexa DXP. -When you specify a segment, you can activate it on multiple communication channels, such as newsletters or commercials. -You can configure multiple activations based data flows. - -First, from the menu bar, select **Activations** and create a new **Ibexa** activation. -Specify name of your activation, select `userid` as **Person Identifier** and click **Next**. - -![General Information - Activation](img/cdp_activation_general_info.png) - -Next, you can fill in **Ibexa information** they must match the ones provided in the YAML configuration: - -- **Client Secret** and **Client ID** - are used to authenticate against Webhook endpoint. In the configuration they are taken from environment variables in `.env` file. - -- **Segment Group Identifier** - identifier of the segment group in Ibexa DXP. It points to a segment group where all the CDP audiences will be stored. -- **Base URL** - URL of your instance with added `/cdp/webhook` at the end. - -![Ibexa Information - Activation](img/cdp_activation_ibexa_info.png) - -Finally, you can specify the audiences you wish to include. - -!!! note "CDP requests" - - All CDP requests are logged in with `debug` severity. - -## Add Client-side Tracking - -The final step is setting up a tracking script. -It requires a head tracking script between the `` tags on your website -and a main script after the head script, and cookie consent. -You can do it by following [tutorial in the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/115000656909-Client-side-Tracking). - -Now, you need to add a tracker to specific places in your website where you want to track users. -For example, add this tracker to the Landing Page template if you want to track user entrances. - -```js -raptor.trackEvent('visit', ..., ...); -``` -or buys: - -```js - //Parameters for Product 1 -raptor.trackEvent('buy', ..., ...); - //Parameters for Product 2 -raptor.trackEvent('buy', ..., ...); -``` - -For tracing to be effective, you also need to send ID of a logged-in user in the same way. -Add the user ID information by using below script: - -```js -raptor.push("setRuid","USER_ID_HERE") -``` - -For more information on tracking events, see [the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/201912411-Tracking-Events). diff --git a/docs/cdp/cdp_data_export.md b/docs/cdp/cdp_data_export.md new file mode 100644 index 0000000000..baa98f6582 --- /dev/null +++ b/docs/cdp/cdp_data_export.md @@ -0,0 +1,86 @@ +--- +description: Data export in Ibexa CDP. +--- + +# Data export + +## Extensibility +​ +You can customize Content, User and Product data exported to CDP and you can control what Field Type information you want to export. +By default, custom Field Types have basic export functionality that casts their `Value` object to string ,thanks to `\Stringable` implementation. +​ +## Exporting FieldTypes +​ +Field Types are exported with metadata, for example, ID, Field Definition name, type, value. You can also provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldProcessorInterface` instance to extend metadata. Provided implementation has to be defined as a service and tagged with `ibexa.cdp.export.content.field_processor`. Additionally, you can specify `priority` to override default behavior. All system Field Processors use `-100` priority, anything with higher priority value overrides them. +​ +The interface is simple and has two methods that you need to provide: + +- **supports** method - decides whether your `FieldProcessor` can work with this Field instance. +- **process** method - takes `Field` instance and returns flat array with scalar values which is merged to the payload data. +​ +A typical FieldType will be serialized to: +​ +```json +{ + "field_measurement_simple_id": 1792, + "field_measurement_simple_type": "ibexa_measurement", + "field_measurement_simple_language_code": "eng-GB", + "field_measurement_simple_value_measurement": "data transfer rate", + "field_measurement_simple_value_unit_identifier": "megabyte per second", + "field_measurement_simple_value_unit_symbol": "MB/s", + "field_measurement_simple_value_unit_is_base": false, + "field_measurement_simple_value_base_unit_identifier": "bit per second", + "field_measurement_simple_value_base_unit_symbol": "bit/s", + "field_measurement_simple_value_simple": 100, + "field_measurement_simple_value_simple_base_unit": 800000000 +} +``` +​ +Keys are automatically prefixed with Field identifier. Only scalar values are allowed. +​ +### Built in Field Processors for custom Field Types +​ +There are a few system Field Processors that you can use when providing CDP export functionality to your custom Field Type: +​ +### `\Ibexa\Cdp\Export\Content\FieldProcessor\SkippingFieldProcessor` +​ +Causes FieldType to be completely omitted from exported payload. To avoid adding your Field Type data to the payload, register a new service as follows: +​ +```yaml +custom_fieldtype.cdp.export.field_processor: + class: Ibexa\Cdp\Export\Content\FieldProcessor\SkippingFieldProcessor + autoconfigure: false + arguments: + $fieldTypeIdentifier: custom_fieldtype + tags: + - { name: 'ibexa.cdp.export.content.field_processor', priority: 0 } +``` +​ +## Exporting FieldType values +​ +To customize how your FieldType's value is exported, you can provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldValueProcessorInterface` instance. Your implementation has to be registered as a service manually or by autoconfiguration. The service have to use the tag `ibexa.cdp.export.content.field_value_processor`, optionally you can provide `priority` property to override other Field Value Processors. +​ +* `FieldValueProcessorInterface::process` - this method takes `Field` instance and returns an `array` with simple scalar values that are applied to export data payload. If your FieldType returns signle value, provide `value` key in the array. You can return multiple values. A good example is Measurement FieldType where we can return measurements in configured unit as well as base unit, which makes easier comparisons in CDP Audience Builder. +* `FieldValueProcessorInterface::supports` - Decides if `FieldValueProcessor` can work with this `Field`. +​ +### Built in Field Value Processors for custom Field Types +​ +There are a few system Field Value Processors that either work by default or can be registered for custom Field Types: +​ +### `\Ibexa\Cdp\Export\Content\FieldValueProcessor\CastToStringFieldValueProcessor` +​ +This is the default Field Value Processor that is used when no other FieldValueProcessor with higher priority has been registered. It leverages `\Stringable` implementation of FieldType's `\Ibexa\Core\FieldType\Value` object to use as a value in the final payload. +​ +### `\Ibexa\Cdp\Export\Content\FieldValueProcessor\JsonHashFieldValueProcessor` +​ +This Field Value Processor will output JSON data from hash representation of the Field Type (`\Ibexa\Contracts\Core\FieldType\FieldType::toHash` method is being used). This can be useful in some cases, however CDP has no colum mapping that lets you match records on JSON data directly. A basic string comparison can be used but it may not fit your use case. `JsonHashFieldValueProcessor` can be used by registering new service: +​ +```yaml +custom_fieldtype.cdp.export.field_processor: + class: Ibexa\Cdp\Export\Content\FieldValueProcessor\JsonHashFieldValueProcessor + autoconfigure: false + arguments: + $fieldTypeIdentifier: custom_fieldtype + tags: + - { name: 'ibexa.cdp.export.content.field_value_processor', priority: 0 } +``` \ No newline at end of file diff --git a/docs/cdp/cdp_global_configuration.md b/docs/cdp/cdp_global_configuration.md new file mode 100644 index 0000000000..ffad903476 --- /dev/null +++ b/docs/cdp/cdp_global_configuration.md @@ -0,0 +1,59 @@ +--- +description: Global configuration of Ibexa CDP. +--- + +# CDP global configuration + +## Configuration + +Global configuration in Ibexa CDP allows you to automate the process of exporting content, users and products. +To do it, use the `ibexa_cdp` [configuration key](configuration.md#configuration-files): + +```yaml +ibexa_cdp: + data_export: + schedule: + user: + - + interval: '*/15 * * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --user-content-type=user --no-draft' + - + interval: '0 */6 * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --user-content-type=user --no-draft' + content: + - + interval: '*/30 * * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --content-type=article --no-draft' + - + interval: '0 */12 * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --content-type=article --no-draft' + product: + - + interval: '*/30 * * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --product-type=computer --no-draft' + - + interval: '0 */12 * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --product-type=computer --no-draft' +``` + +Accepted options can be listed by running `php bin/console ibexa:cdp:stream-user-data --help` + +Under `schedule` setting you can find separate sections for exporting users, content and product. +Structure of each section is exactly the same and includes `interval` and `options` elements: + +```yaml +- + interval: '0 */12 * * *' + options: '--stream-id=00000000-00000000-00000000-00000000 --content-type=article --no-draft' +``` + +It allows you to provide multiple export tools with parameters. This is important because each type of content/product must have its own parameters on the CDP website, where each has a different Stream ID key and different required values, e.g. `--content-type`. + +You need to fill in settings in the YAML configuration: + +- **Interval** - sets the frequency of invoking the command, for example: '*/30 * * * *' - every 30 minutes, '0 */12 * * *' - every 12 hours. +It uses standard `crontab` format (see: https://crontab.guru/examples.html). +- **Options** - allows you to add arguments that have to be passed to the export authorities. + + + diff --git a/docs/cdp/cdp_product_activation.md b/docs/cdp/cdp_product_activation.md deleted file mode 100644 index d6084c3d91..0000000000 --- a/docs/cdp/cdp_product_activation.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -description: Step-by-step activation procedure of Ibexa CDP. ---- - -# CDP activation - -## Configuration - -To configure Ibexa CDP, use the `ibexa.system..cdp` [configuration key](configuration.md#configuration-files): - -```yaml -ibexa_cdp: - data_export: - schedule: - product: - # You can use examples below to build your own data export schedule. - # Accepted options can be listed by running `php bin/console ibexa:cdp:stream-product-data --help` - # every 30 minutes - - - interval: '*/30 * * * *' - options: '--stream-id=00000000-00000000-00000000-00000000 --product-type=computer --no-draft' -​ - # every 12 hours - - - interval: '0 */12 * * *' - options: '--stream-id=00000000-00000000-00000000-00000000 --product-type=computer --no-draft' -​ -``` - -All configuration settings are described below. -You can follow them step by step to set up your Ibexa CDP. - -### Segment group - -First, create a segment group in the Back Office. -It will serve as a container for all segments data generated by Ibexa CDP. -Go to **Admin** -> **Segments** and select **Create**. -Fill in name and identifier for a segment group. -Choose wisely, as once connected to CDP Segment Group cannot be changed. - -![Creating a new segment group](img/cdp_create_segment_group.png) - -Next, add a segment group identifier to the configuration. - -!!! caution "Ibexa CDP Segment Group" - - After you create the Segment Group in the Back Office and connect it to Ibexa CDP, you cannot change it in any way, including edit its name. - -## Account number - -Now, fill in the account number. -Log in to Ibexa CDP and in the top right corner, select available accounts. - -![List of available accounts](img/cdp_accounts.png) - -A pop-up window displays with a list of all available accounts and their numbers. - -![Account number](img/cdp_account_number.png) - -## Data export - -You need to specify a source of the user data that Ibexa CDP will connect to. -To do so, go to **Data Manager** in **Tools** section and select **Create new dataflow**. -It will take you to a Dataflow Creator, where in five steps you will set up a data streaming. - -### General Information - -In the **General Information** section, specify dataflow name, -choose **Stream File** as a source of user data and **CDP** as a destination, -where they will be sent for processing. -Currently, only Stream File transport is supported and can be initialized from the configuration. - -### Download - -In the **Download** section, select **Stream file**. -Copy generated steam ID and paste it into the configuration file under `stream_id`. -It allows you to establish a datastream from the Streaming API into the Data Manager. - -Next, you need to export your user data to the CDP. -Go to your installation and use this command: - -```bash -php bin/console ibexa:cdp:stream-user-data --draft -``` - -There are two versions of this command `--draft/--no-draft`. -The first one is used to send the test user data to the Data Manager. -If it passes a validation test in the **Activation** section, use the latter one to send a full version. - -Next, go back to Ibexa CDP and select **Validate & download**. -If the file passes, you will see a confirmation message. -Now, you can go to the **File mapping** section. - -### File mapping - -Mapping is completed automatically, the system fills all required information and shows available columns with datapoints on the right. -You can change their names if needed or disallow empty fields by checking **Mandatory**. -If the provided file contains empty values, this option is not available. - -If provided file is not recognized, the system will require you to fill in the parsing-options manually or select an appropriate format. -If you make any alterations, select the **Parse File** to generate columns with new data. - -### Transform & Map - -In the **Transform & Map** section you transform data and map it to a schema. -At this point, you can map **email** to **email** and **id** to **integer** fields to get custom columns. - -Next, select **Create schema based on the downloaded columns**. -It will move you to Schema Creator. -There, choose **PersonalData** as a parent and name the schema. - -![Create new schema](img/cdp_create_new_schema.png) - -Next, select all the columns and set Person Identifier as **userid**. - -![Person Identifier](img/cdp_person_identifier.png) - -If you used PersonData or Catalog type schemas, the system will require -specifying the Write Mode that will be applied to them. - -**Append** (default one) allows new data to overwrite the old one but leaves existing entries unaffected. -All entries are stored in the dataset, unchanged by updating dataflow. -For example, if a customer unsubscribes a newsletter, their email will remain in the system. -**Overwrite** completely removes the original dataset and replaces it with the new one every time the dataflow runs. - -Next, select **userid** from a **Schema columns section** on the right and map it to **id**. - -![Map userid to id](img/cdp_userid_mapid.png) - -### Activation - -In this section you will test the dataflow with provided test user data. -If everything passes, go to your installation and export production data with this command: - -```bash -php bin/console ibexa:cdp:stream-user-data --no-draft -``` - -Now you can run and activate the dataflow. - -### Build new Audience/Segment - -Go to the **Audience Builder** and select **Build new audience**. -When naming the audience remember, you will need to find it in a drop-down list during activation. -There, you can choose conditions from `did`, `did not` or `have`. -The conditions `did` and `did not` allow you to use events like buy, visit or add to a cart from online tracking. -- `have` conditions are tied to personal characteristics and can be used to track the sum of all buys or top-visited categories. - -In the Audience Builder, you can also connect created audiences to the activations. - -## Activation - -Activation synchronises data from Ibexa CDP to the Ibexa DXP. -When you specify a segment, you can activate it on multiple communication channels, such as newsletters or commercials. -You can configure multiple activations based data flows. - -First, from the menu bar, select **Activations** and create a new **Ibexa** activation. -Specify name of your activation, select `userid` as **Person Identifier** and click **Next**. - -![General Information - Activation](img/cdp_activation_general_info.png) - -Next, you can fill in **Ibexa information** they must match the ones provided in the YAML configuration: - -- **Client Secret** and **Client ID** - are used to authenticate against Webhook endpoint. In the configuration they are taken from environment variables in `.env` file. - -- **Segment Group Identifier** - identifier of the segment group in Ibexa DXP. It points to a segment group where all the CDP audiences will be stored. -- **Base URL** - URL of your instance with added `/cdp/webhook` at the end. - -![Ibexa Information - Activation](img/cdp_activation_ibexa_info.png) - -Finally, you can specify the audiences you wish to include. - -!!! note "CDP requests" - - All CDP requests are logged in with `debug` severity. - -## Add Client-side Tracking - -The final step is setting up a tracking script. -It requires a head tracking script between the `` tags on your website -and a main script after the head script, and cookie consent. -You can do it by following [tutorial in the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/115000656909-Client-side-Tracking). - -Now, you need to add a tracker to specific places in your website where you want to track users. -For example, add this tracker to the Landing Page template if you want to track user entrances. - -```js -raptor.trackEvent('visit', ..., ...); -``` -or buys: - -```js - //Parameters for Product 1 -raptor.trackEvent('buy', ..., ...); - //Parameters for Product 2 -raptor.trackEvent('buy', ..., ...); -``` - -For tracing to be effective, you also need to send ID of a logged-in user in the same way. -Add the user ID information by using below script: - -```js -raptor.push("setRuid","USER_ID_HERE") -``` - -For more information on tracking events, see [the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/201912411-Tracking-Events). diff --git a/docs/cdp/cdp_user_activation.md b/docs/cdp/cdp_user_activation.md deleted file mode 100644 index 6bd428b901..0000000000 --- a/docs/cdp/cdp_user_activation.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -description: Step-by-step activation procedure of Ibexa CDP. ---- - -# CDP activation - -## Configuration - -To configure Ibexa CDP, use the `ibexa.system..cdp` [configuration key](configuration.md#configuration-files): - -```yaml -ibexa_cdp: - data_export: - schedule: - user: - # You can use examples below to build your own data export schedule. - # Accepted options can be listed by running `php bin/console ibexa:cdp:stream-user-data --help` - # every 15 minutes - - - interval: '*/15 * * * *' - options: '--stream-id=00000000-00000000-00000000-00000000 --user-content-type=user --no-draft' -``` - -All configuration settings are described below. -You can follow them step by step to set up your Ibexa CDP. - -### Segment group - -First, create a segment group in the Back Office. -It will serve as a container for all segments data generated by Ibexa CDP. -Go to **Admin** -> **Segments** and select **Create**. -Fill in name and identifier for a segment group. -Choose wisely, as once connected to CDP Segment Group cannot be changed. - -![Creating a new segment group](img/cdp_create_segment_group.png) - -Next, add a segment group identifier to the configuration. - -!!! caution "Ibexa CDP Segment Group" - - After you create the Segment Group in the Back Office and connect it to Ibexa CDP, you cannot change it in any way, including edit its name. - -## Account number - -Now, fill in the account number. -Log in to Ibexa CDP and in the top right corner, select available accounts. - -![List of available accounts](img/cdp_accounts.png) - -A pop-up window displays with a list of all available accounts and their numbers. - -![Account number](img/cdp_account_number.png) - -## Data export - -You need to specify a source of the user data that Ibexa CDP will connect to. -To do so, go to **Data Manager** in **Tools** section and select **Create new dataflow**. -It will take you to a Dataflow Creator, where in five steps you will set up a data streaming. - -### General Information - -In the **General Information** section, specify dataflow name, -choose **Stream File** as a source of user data and **CDP** as a destination, -where they will be sent for processing. -Currently, only Stream File transport is supported and can be initialized from the configuration. - -### Download - -In the **Download** section, select **Stream file**. -Copy generated steam ID and paste it into the configuration file under `stream_id`. -It allows you to establish a datastream from the Streaming API into the Data Manager. - -Next, you need to export your user data to the CDP. -Go to your installation and use this command: - -```bash -php bin/console ibexa:cdp:stream-user-data --draft -``` - -There are two versions of this command `--draft/--no-draft`. -The first one is used to send the test user data to the Data Manager. -If it passes a validation test in the **Activation** section, use the latter one to send a full version. - -Next, go back to Ibexa CDP and select **Validate & download**. -If the file passes, you will see a confirmation message. -Now, you can go to the **File mapping** section. - -### File mapping - -Mapping is completed automatically, the system fills all required information and shows available columns with datapoints on the right. -You can change their names if needed or disallow empty fields by checking **Mandatory**. -If the provided file contains empty values, this option is not available. - -If provided file is not recognized, the system will require you to fill in the parsing-options manually or select an appropriate format. -If you make any alterations, select the **Parse File** to generate columns with new data. - -### Transform & Map - -In the **Transform & Map** section you transform data and map it to a schema. -At this point, you can map **email** to **email** and **id** to **integer** fields to get custom columns. - -Next, select **Create schema based on the downloaded columns**. -It will move you to Schema Creator. -There, choose **PersonalData** as a parent and name the schema. - -![Create new schema](img/cdp_create_new_schema.png) - -Next, select all the columns and set Person Identifier as **userid**. - -![Person Identifier](img/cdp_person_identifier.png) - -If you used PersonData or Catalog type schemas, the system will require -specifying the Write Mode that will be applied to them. - -**Append** (default one) allows new data to overwrite the old one but leaves existing entries unaffected. -All entries are stored in the dataset, unchanged by updating dataflow. -For example, if a customer unsubscribes a newsletter, their email will remain in the system. -**Overwrite** completely removes the original dataset and replaces it with the new one every time the dataflow runs. - -Next, select **userid** from a **Schema columns section** on the right and map it to **id**. - -![Map userid to id](img/cdp_userid_mapid.png) - -### Activation - -In this section you will test the dataflow with provided test user data. -If everything passes, go to your installation and export production data with this command: - -```bash -php bin/console ibexa:cdp:stream-user-data --no-draft -``` - -Now you can run and activate the dataflow. - -### Build new Audience/Segment - -Go to the **Audience Builder** and select **Build new audience**. -When naming the audience remember, you will need to find it in a drop-down list during activation. -There, you can choose conditions from `did`, `did not` or `have`. -The conditions `did` and `did not` allow you to use events like buy, visit or add to a cart from online tracking. -- `have` conditions are tied to personal characteristics and can be used to track the sum of all buys or top-visited categories. - -In the Audience Builder, you can also connect created audiences to the activations. - -## Activation - -Activation synchronises data from Ibexa CDP to the Ibexa DXP. -When you specify a segment, you can activate it on multiple communication channels, such as newsletters or commercials. -You can configure multiple activations based data flows. - -First, from the menu bar, select **Activations** and create a new **Ibexa** activation. -Specify name of your activation, select `userid` as **Person Identifier** and click **Next**. - -![General Information - Activation](img/cdp_activation_general_info.png) - -Next, you can fill in **Ibexa information** they must match the ones provided in the YAML configuration: - -- **Client Secret** and **Client ID** - are used to authenticate against Webhook endpoint. In the configuration they are taken from environment variables in `.env` file. - -- **Segment Group Identifier** - identifier of the segment group in Ibexa DXP. It points to a segment group where all the CDP audiences will be stored. -- **Base URL** - URL of your instance with added `/cdp/webhook` at the end. - -![Ibexa Information - Activation](img/cdp_activation_ibexa_info.png) - -Finally, you can specify the audiences you wish to include. - -!!! note "CDP requests" - - All CDP requests are logged in with `debug` severity. - -## Add Client-side Tracking - -The final step is setting up a tracking script. -It requires a head tracking script between the `` tags on your website -and a main script after the head script, and cookie consent. -You can do it by following [tutorial in the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/115000656909-Client-side-Tracking). - -Now, you need to add a tracker to specific places in your website where you want to track users. -For example, add this tracker to the Landing Page template if you want to track user entrances. - -```js -raptor.trackEvent('visit', ..., ...); -``` -or buys: - -```js - //Parameters for Product 1 -raptor.trackEvent('buy', ..., ...); - //Parameters for Product 2 -raptor.trackEvent('buy', ..., ...); -``` - -For tracing to be effective, you also need to send ID of a logged-in user in the same way. -Add the user ID information by using below script: - -```js -raptor.push("setRuid","USER_ID_HERE") -``` - -For more information on tracking events, see [the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/201912411-Tracking-Events). From 873f41cbf9c8e0393d91ded1d0ccd01fdb1410e9 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Fri, 6 Oct 2023 12:59:33 +0200 Subject: [PATCH 03/13] Updates --- docs/cdp/cdp_data_export.md | 52 ++++++++++++++++------------ docs/cdp/cdp_global_configuration.md | 29 ++++++---------- mkdocs.yml | 2 ++ 3 files changed, 43 insertions(+), 40 deletions(-) diff --git a/docs/cdp/cdp_data_export.md b/docs/cdp/cdp_data_export.md index baa98f6582..972eb27ee0 100644 --- a/docs/cdp/cdp_data_export.md +++ b/docs/cdp/cdp_data_export.md @@ -7,18 +7,18 @@ description: Data export in Ibexa CDP. ## Extensibility ​ You can customize Content, User and Product data exported to CDP and you can control what Field Type information you want to export. -By default, custom Field Types have basic export functionality that casts their `Value` object to string ,thanks to `\Stringable` implementation. +By default, custom Field Types have basic export functionality. It casts their `Value` object to string, thanks to `\Stringable` implementation. ​ -## Exporting FieldTypes +## Exporting Field Types ​ -Field Types are exported with metadata, for example, ID, Field Definition name, type, value. You can also provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldProcessorInterface` instance to extend metadata. Provided implementation has to be defined as a service and tagged with `ibexa.cdp.export.content.field_processor`. Additionally, you can specify `priority` to override default behavior. All system Field Processors use `-100` priority, anything with higher priority value overrides them. -​ -The interface is simple and has two methods that you need to provide: +Field Types are exported with metadata, for example, ID, Field Definition name, type, value. You can also provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldProcessorInterface` instance to extend metadata. Provided implementation has to be defined as a service and tagged with `ibexa.cdp.export.content.field_processor`. Additionally, you can specify `priority` to override default behavior. All system Field Processors use `-100` priority, and any higher priority value overrides them. + +The interface is plain and has two methods that you need to provide: -- **supports** method - decides whether your `FieldProcessor` can work with this Field instance. -- **process** method - takes `Field` instance and returns flat array with scalar values which is merged to the payload data. +- **supports** - decides whether your `FieldProcessor` can work with the `Field` instance. +- **process** - takes `Field` instance and then returns a flat array of scalar values that are combined with the payload data. ​ -A typical FieldType will be serialized to: +A common Field Type is serialized to: ​ ```json { @@ -36,15 +36,16 @@ A typical FieldType will be serialized to: } ``` ​ -Keys are automatically prefixed with Field identifier. Only scalar values are allowed. +Field identifier is a prefix that is automatically added to each key. You can only use scalar values. ​ ### Built in Field Processors for custom Field Types ​ -There are a few system Field Processors that you can use when providing CDP export functionality to your custom Field Type: -​ -### `\Ibexa\Cdp\Export\Content\FieldProcessor\SkippingFieldProcessor` +You may provide your own CDP export functionality by using one of the system Field Processors: + +#### `\Ibexa\Cdp\Export\Content\FieldProcessor\SkippingFieldProcessor`. ​ -Causes FieldType to be completely omitted from exported payload. To avoid adding your Field Type data to the payload, register a new service as follows: +It results in the Field Type being excluded from the exported payload. +To avoid adding the Field Type data to the payload, register a new service as follow: ​ ```yaml custom_fieldtype.cdp.export.field_processor: @@ -56,24 +57,31 @@ custom_fieldtype.cdp.export.field_processor: - { name: 'ibexa.cdp.export.content.field_processor', priority: 0 } ``` ​ -## Exporting FieldType values +## Exporting Field Type values ​ -To customize how your FieldType's value is exported, you can provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldValueProcessorInterface` instance. Your implementation has to be registered as a service manually or by autoconfiguration. The service have to use the tag `ibexa.cdp.export.content.field_value_processor`, optionally you can provide `priority` property to override other Field Value Processors. +To customize export of Field Type values, provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldValueProcessorInterface` instance. +YNew implementation has to be registered as a service manually or by using autoconfiguration. The service has to use the tag `ibexa.cdp.export.content.field_value_processor`, you can also provide `priority` property to override other Field Value Processors. ​ -* `FieldValueProcessorInterface::process` - this method takes `Field` instance and returns an `array` with simple scalar values that are applied to export data payload. If your FieldType returns signle value, provide `value` key in the array. You can return multiple values. A good example is Measurement FieldType where we can return measurements in configured unit as well as base unit, which makes easier comparisons in CDP Audience Builder. -* `FieldValueProcessorInterface::supports` - Decides if `FieldValueProcessor` can work with this `Field`. +* `FieldValueProcessorInterface::process` - takes `Field` instance and returns an `array` with scalar values that are applied to export data payload. If th Field Type returns single value, provide `value` key in the array. You can return multiple values. +* `FieldValueProcessorInterface::supports` - decides whether `FieldValueProcessor` can work with the `Field`. ​ ### Built in Field Value Processors for custom Field Types ​ -There are a few system Field Value Processors that either work by default or can be registered for custom Field Types: +There are few system Field Value Processors that either work by default or can be registered for custom Field Types: ​ -### `\Ibexa\Cdp\Export\Content\FieldValueProcessor\CastToStringFieldValueProcessor` +#### `\Ibexa\Cdp\Export\Content\FieldValueProcessor\CastToStringFieldValueProcessor` ​ -This is the default Field Value Processor that is used when no other FieldValueProcessor with higher priority has been registered. It leverages `\Stringable` implementation of FieldType's `\Ibexa\Core\FieldType\Value` object to use as a value in the final payload. +This Processor is a default one, as long as no other Processor with higher priority is registered. It makes `\Stringable` implementation of the Field Type `\Ibexa\Core\FieldType\Value` object to use it as a value in the final payload. ​ -### `\Ibexa\Cdp\Export\Content\FieldValueProcessor\JsonHashFieldValueProcessor` +#### `\Ibexa\Cdp\Export\Content\FieldValueProcessor\JsonHashFieldValueProcessor` ​ -This Field Value Processor will output JSON data from hash representation of the Field Type (`\Ibexa\Contracts\Core\FieldType\FieldType::toHash` method is being used). This can be useful in some cases, however CDP has no colum mapping that lets you match records on JSON data directly. A basic string comparison can be used but it may not fit your use case. `JsonHashFieldValueProcessor` can be used by registering new service: +This Processor generates JSON data from hash representation of the Field Type (it uses `\Ibexa\Contracts\Core\FieldType\FieldType::toHash` method). + +!!! warning + + CDP doesn't support column mapping, which allows you to match records on JSON data directly. + +To use `JsonHashFieldValueProcessor`, you need to register a new service: ​ ```yaml custom_fieldtype.cdp.export.field_processor: diff --git a/docs/cdp/cdp_global_configuration.md b/docs/cdp/cdp_global_configuration.md index ffad903476..67c56d0c00 100644 --- a/docs/cdp/cdp_global_configuration.md +++ b/docs/cdp/cdp_global_configuration.md @@ -4,10 +4,10 @@ description: Global configuration of Ibexa CDP. # CDP global configuration -## Configuration +## Configuration key -Global configuration in Ibexa CDP allows you to automate the process of exporting content, users and products. -To do it, use the `ibexa_cdp` [configuration key](configuration.md#configuration-files): +Global configuration in Ibexa CDP allows you to automate the process of exporting Content, Users and Products. +Global `ibexa_cdp` [configuration key](configuration.md#configuration-files) looks as below: ```yaml ibexa_cdp: @@ -36,24 +36,17 @@ ibexa_cdp: options: '--stream-id=00000000-00000000-00000000-00000000 --product-type=computer --no-draft' ``` -Accepted options can be listed by running `php bin/console ibexa:cdp:stream-user-data --help` - -Under `schedule` setting you can find separate sections for exporting users, content and product. +Under `schedule` setting you can find separate sections for exporting User, Content, and Product. Structure of each section is exactly the same and includes `interval` and `options` elements: -```yaml -- - interval: '0 */12 * * *' - options: '--stream-id=00000000-00000000-00000000-00000000 --content-type=article --no-draft' -``` - -It allows you to provide multiple export tools with parameters. This is important because each type of content/product must have its own parameters on the CDP website, where each has a different Stream ID key and different required values, e.g. `--content-type`. - -You need to fill in settings in the YAML configuration: - -- **Interval** - sets the frequency of invoking the command, for example: '*/30 * * * *' - every 30 minutes, '0 */12 * * *' - every 12 hours. +- **Interval** - sets the frequency of the command invoke, for example, '*/30 * * * *' - every 30 minutes, '0 */12 * * *' - every 12 hours. It uses standard `crontab` format (see: https://crontab.guru/examples.html). -- **Options** - allows you to add arguments that have to be passed to the export authorities. +- **Options** - allows you to add arguments that have to be passed to the export command. +This configuration allows you to provide multiple export tools with parameters. It's important, because each type of content/product must have its own parameters on the CDP website, where each has a different Stream ID key and different required values, for example, `--content-type`. +Accepted options can be listed with this command: +```bash +php bin/console ibexa:cdp:stream-user-data --help +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 897d4513b7..0538548368 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -409,6 +409,8 @@ nav: - Customer Data Platform: cdp/cdp.md - CDP installation: cdp/cdp_installation.md - CDP activation: cdp/cdp_activation.md + - CDP global configuration: cdp/cdp_global_configuration.md + - CDP data export: cdp/cdp_data_export.md - Search: - Search: search/search.md - Search engines: From 8c5300db8a1527cdf794c119d8cce71735c95538 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Thu, 12 Oct 2023 14:20:25 +0200 Subject: [PATCH 04/13] Page name updated --- ..._global_configuration.md => cdp_data_export_schedule.md} | 6 +++--- mkdocs.yml | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) rename docs/cdp/{cdp_global_configuration.md => cdp_data_export_schedule.md} (92%) diff --git a/docs/cdp/cdp_global_configuration.md b/docs/cdp/cdp_data_export_schedule.md similarity index 92% rename from docs/cdp/cdp_global_configuration.md rename to docs/cdp/cdp_data_export_schedule.md index 67c56d0c00..8ff8e24a46 100644 --- a/docs/cdp/cdp_global_configuration.md +++ b/docs/cdp/cdp_data_export_schedule.md @@ -1,12 +1,12 @@ --- -description: Global configuration of Ibexa CDP. +description: Data export schedule in Ibexa CDP. --- -# CDP global configuration +# CDP data export schedule ## Configuration key -Global configuration in Ibexa CDP allows you to automate the process of exporting Content, Users and Products. +Configuration in Ibexa CDP allows you to automate the process of exporting Content, Users and Products. Global `ibexa_cdp` [configuration key](configuration.md#configuration-files) looks as below: ```yaml diff --git a/mkdocs.yml b/mkdocs.yml index 0538548368..ae6526a386 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -409,7 +409,7 @@ nav: - Customer Data Platform: cdp/cdp.md - CDP installation: cdp/cdp_installation.md - CDP activation: cdp/cdp_activation.md - - CDP global configuration: cdp/cdp_global_configuration.md + - CDP data export schedule: cdp/cdp_data_export_schedule.md - CDP data export: cdp/cdp_data_export.md - Search: - Search: search/search.md From 2eb025c5a52e15875263d6aa3ebd9f50ed29c2b4 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Tue, 31 Oct 2023 11:31:33 +0100 Subject: [PATCH 05/13] Structure changed --- docs/cdp/cdp_activation/cdp_activation.md | 14 +++ .../cdp_add_clientside_tracking.md | 34 ++++++ docs/cdp/cdp_activation/cdp_configuration.md | 55 ++++++++++ .../cdp_data_export.md} | 101 ++---------------- docs/cdp/cdp_data_export_schedule.md | 4 +- ...p_data_export.md => cdp_data_extension.md} | 6 +- mkdocs.yml | 7 +- 7 files changed, 120 insertions(+), 101 deletions(-) create mode 100644 docs/cdp/cdp_activation/cdp_activation.md create mode 100644 docs/cdp/cdp_activation/cdp_add_clientside_tracking.md create mode 100644 docs/cdp/cdp_activation/cdp_configuration.md rename docs/cdp/{cdp_activation.md => cdp_activation/cdp_data_export.md} (61%) rename docs/cdp/{cdp_data_export.md => cdp_data_extension.md} (98%) diff --git a/docs/cdp/cdp_activation/cdp_activation.md b/docs/cdp/cdp_activation/cdp_activation.md new file mode 100644 index 0000000000..7ff878e6a3 --- /dev/null +++ b/docs/cdp/cdp_activation/cdp_activation.md @@ -0,0 +1,14 @@ +--- +description: Step-by-step activation procedure of [[= product_name_cdp =]]. +page_type: landing_page +--- + +# Administration + +Follow step-by-step activation procedure of [[= product_name_cdp =]]. + +[[= cards([ + "cdp/cdp_activation/cdp_configuration", + "cdp/cdp_activation/cdp_data_export", + "cdp/cdp_activation/cdp_add_clientside_tracking", +], columns=3) =]] \ No newline at end of file diff --git a/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md b/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md new file mode 100644 index 0000000000..19cd699b75 --- /dev/null +++ b/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md @@ -0,0 +1,34 @@ +--- +description: Client-side Tracking in [[= product_name_cdp =]]. +--- + +# Add Client-side Tracking + +The final step is setting up a tracking script. +It requires a head tracking script between the `` tags on your website +and a main script after the head script, and cookie consent. +You can do it by following [tutorial in the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/115000656909-Client-side-Tracking). + +Now, you need to add a tracker to specific places in your website where you want to track users. +For example, add this tracker to the Landing Page template if you want to track user entrances. + +```js +raptor.trackEvent('visit', ..., ...); +``` +or buys: + +```js + //Parameters for Product 1 +raptor.trackEvent('buy', ..., ...); + //Parameters for Product 2 +raptor.trackEvent('buy', ..., ...); +``` + +For tracing to be effective, you also need to send ID of a logged-in user in the same way. +Add the user ID information by using below script: + +```js +raptor.push("setRuid","USER_ID_HERE") +``` + +For more information on tracking events, see [the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/201912411-Tracking-Events). \ No newline at end of file diff --git a/docs/cdp/cdp_activation/cdp_configuration.md b/docs/cdp/cdp_activation/cdp_configuration.md new file mode 100644 index 0000000000..efb4bdc429 --- /dev/null +++ b/docs/cdp/cdp_activation/cdp_configuration.md @@ -0,0 +1,55 @@ +--- +description: Step-by-step configuration procedure of [[= product_name_cdp =]] +--- + +# Configuration + +To configure [[= product_name_cdp =]], use the `ibexa.system..cdp` [configuration key](configuration.md#configuration-files): + +```yaml +ibexa: + system: + default: + cdp: + account_number: 123456 + data_export: + user_data: + transport: stream_file + stream_file: + stream_id: 00000000-00000000-00000000-00000000 + activations: + - + client_id: '%env(CDP_ACTIVATION_CLIENT_ID)%' + client_secret: '%env(CDP_ACTIVATION_CLIENT_SECRET)%' + segment_group_identifier: example_segment_group_identifier +``` + +All configuration settings are described below. +You can follow them step by step to set up your [[= product_name_cdp =]]. + +## Segment group + +First, create a segment group in the Back Office. +It will serve as a container for all segments data generated by [[= product_name_cdp =]]. +Go to **Admin** -> **Segments** and select **Create**. +Fill in name and identifier for a segment group. +Choose wisely, as once connected to CDP Segment Group cannot be changed. + +![Creating a new segment group](img/cdp_create_segment_group.png) + +Next, add a segment group identifier to the configuration. + +!!! caution "[[= product_name_cdp =]] Segment Group" + + After you create the Segment Group in the Back Office and connect it to [[= product_name_cdp =]], you cannot change it in any way, including edit its name. + +## Account number + +Now, fill in the account number. +Log in to [[= product_name_cdp =]] and in the top right corner, select available accounts. + +![List of available accounts](img/cdp_accounts.png) + +A pop-up window displays with a list of all available accounts and their numbers. + +![Account number](img/cdp_account_number.png) diff --git a/docs/cdp/cdp_activation.md b/docs/cdp/cdp_activation/cdp_data_export.md similarity index 61% rename from docs/cdp/cdp_activation.md rename to docs/cdp/cdp_activation/cdp_data_export.md index 0156b3a423..ecff4d1886 100644 --- a/docs/cdp/cdp_activation.md +++ b/docs/cdp/cdp_activation/cdp_data_export.md @@ -1,75 +1,21 @@ --- -description: Step-by-step activation procedure of Ibexa CDP. +description: Step-by-step data export procedure of [[= product_name_cdp =]]. --- -# CDP activation - -## Configuration - -To configure [[= product_name_cdp =]], use the `ibexa.system..cdp` [configuration key](configuration.md#configuration-files): - -```yaml -ibexa: - system: - default: - cdp: - account_number: 123456 - data_export: - user_data: - transport: stream_file - stream_file: - stream_id: 00000000-00000000-00000000-00000000 - activations: - - - client_id: '%env(CDP_ACTIVATION_CLIENT_ID)%' - client_secret: '%env(CDP_ACTIVATION_CLIENT_SECRET)%' - segment_group_identifier: example_segment_group_identifier -``` - -All configuration settings are described below. -You can follow them step by step to set up your [[= product_name_cdp =]]. - -### Segment group - -First, create a segment group in the Back Office. -It will serve as a container for all segments data generated by [[= product_name_cdp =]]. -Go to **Admin** -> **Segments** and select **Create**. -Fill in name and identifier for a segment group. -Choose wisely, as once connected to CDP Segment Group cannot be changed. - -![Creating a new segment group](img/cdp_create_segment_group.png) - -Next, add a segment group identifier to the configuration. - -!!! caution "[[= product_name_cdp =]] Segment Group" - - After you create the Segment Group in the Back Office and connect it to [[= product_name_cdp =]], you cannot change it in any way, including edit its name. - -## Account number - -Now, fill in the account number. -Log in to [[= product_name_cdp =]] and in the top right corner, select available accounts. - -![List of available accounts](img/cdp_accounts.png) - -A pop-up window displays with a list of all available accounts and their numbers. - -![Account number](img/cdp_account_number.png) - -## Data export +# Data export You need to specify a source of the user data that [[= product_name_cdp =]] will connect to. To do so, go to **Data Manager** in **Tools** section and select **Create new dataflow**. It will take you to a Dataflow Creator, where in five steps you will set up a data streaming. -### General Information +## General Information In the **General Information** section, specify dataflow name, choose **Stream File** as a source of user data and **CDP** as a destination, where they will be sent for processing. Currently, only Stream File transport is supported and can be initialized from the configuration. -### Download +## Download In the **Download** section, select **Stream file**. Copy generated steam ID and paste it into the configuration file under `stream_id`. @@ -90,7 +36,7 @@ Next, go back to [[= product_name_cdp =]] and select **Validate & download**. If the file passes, you will see a confirmation message. Now, you can go to the **File mapping** section. -### File mapping +## File mapping Mapping is completed automatically, the system fills all required information and shows available columns with datapoints on the right. You can change their names if needed or disallow empty fields by checking **Mandatory**. @@ -99,7 +45,7 @@ If the provided file contains empty values, this option is not available. If provided file is not recognized, the system will require you to fill in the parsing-options manually or select an appropriate format. If you make any alterations, select the **Parse File** to generate columns with new data. -### Transform & Map +## Transform & Map In the **Transform & Map** section you transform data and map it to a schema. At this point, you can map **email** to **email** and **id** to **integer** fields to get custom columns. @@ -126,7 +72,7 @@ Next, select **userid** from a **Schema columns section** on the right and map i ![Map userid to id](img/cdp_userid_mapid.png) -### Activation +## Activation In this section you will test the dataflow with provided test user data. If everything passes, go to your installation and export production data with this command: @@ -137,7 +83,7 @@ php bin/console ibexa:cdp:stream-user-data --no-draft Now you can run and activate the dataflow. -### Build new Audience/Segment +## Build new Audience/Segment Go to the **Audience Builder** and select **Build new audience**. When naming the audience remember, you will need to find it in a drop-down list during activation. @@ -172,34 +118,3 @@ Finally, you can specify the audiences you wish to include. !!! note "CDP requests" All CDP requests are logged in with `debug` severity. - -## Add Client-side Tracking - -The final step is setting up a tracking script. -It requires a head tracking script between the `` tags on your website -and a main script after the head script, and cookie consent. -You can do it by following [tutorial in the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/115000656909-Client-side-Tracking). - -Now, you need to add a tracker to specific places in your website where you want to track users. -For example, add this tracker to the Landing Page template if you want to track user entrances. - -```js -raptor.trackEvent('visit', ..., ...); -``` -or buys: - -```js - //Parameters for Product 1 -raptor.trackEvent('buy', ..., ...); - //Parameters for Product 2 -raptor.trackEvent('buy', ..., ...); -``` - -For tracing to be effective, you also need to send ID of a logged-in user in the same way. -Add the user ID information by using below script: - -```js -raptor.push("setRuid","USER_ID_HERE") -``` - -For more information on tracking events, see [the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/201912411-Tracking-Events). diff --git a/docs/cdp/cdp_data_export_schedule.md b/docs/cdp/cdp_data_export_schedule.md index 8ff8e24a46..5f91a04bdf 100644 --- a/docs/cdp/cdp_data_export_schedule.md +++ b/docs/cdp/cdp_data_export_schedule.md @@ -1,12 +1,12 @@ --- -description: Data export schedule in Ibexa CDP. +description: Data export schedule in [[= product_name_cdp =]]. --- # CDP data export schedule ## Configuration key -Configuration in Ibexa CDP allows you to automate the process of exporting Content, Users and Products. +Configuration in [[= product_name_cdp =]] allows you to automate the process of exporting Content, Users and Products. Global `ibexa_cdp` [configuration key](configuration.md#configuration-files) looks as below: ```yaml diff --git a/docs/cdp/cdp_data_export.md b/docs/cdp/cdp_data_extension.md similarity index 98% rename from docs/cdp/cdp_data_export.md rename to docs/cdp/cdp_data_extension.md index 972eb27ee0..b6fc8cb884 100644 --- a/docs/cdp/cdp_data_export.md +++ b/docs/cdp/cdp_data_extension.md @@ -1,10 +1,8 @@ --- -description: Data export in Ibexa CDP. +description: Data extension in [[= product_name_cdp =]]. --- -# Data export - -## Extensibility +# Data extension ​ You can customize Content, User and Product data exported to CDP and you can control what Field Type information you want to export. By default, custom Field Types have basic export functionality. It casts their `Value` object to string, thanks to `\Stringable` implementation. diff --git a/mkdocs.yml b/mkdocs.yml index ae6526a386..a03e3d5a9f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -408,9 +408,12 @@ nav: - CDP (Customer Data Platform): - Customer Data Platform: cdp/cdp.md - CDP installation: cdp/cdp_installation.md - - CDP activation: cdp/cdp_activation.md + - CDP activation: cdp/cdp_activation/cdp_activation.md + - CDP configuration: cdp/cdp_activation/cdp_configuration.md + - CDP data export: cdp/cdp_activation/cdp_data_export.md + - CDP add client-side tracking: cdp/cdp_activation/cdp_add_clientside_tracking.md - CDP data export schedule: cdp/cdp_data_export_schedule.md - - CDP data export: cdp/cdp_data_export.md + - CDP data export: cdp/cdp_data_extension.md - Search: - Search: search/search.md - Search engines: From 3616c061db28d3524c5788f9170d3d68b9d25104 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Fri, 13 Oct 2023 14:32:26 +0200 Subject: [PATCH 06/13] Updates --- .vscode/settings.json | 3 +++ docs/cdp/cdp_activation/cdp_configuration.md | 20 +++++++++++++++----- docs/cdp/cdp_activation/cdp_data_export.md | 16 +++++++++++++++- 3 files changed, 33 insertions(+), 6 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000000..e553f50970 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "vale.valeCLI.config": "/Users/julitafalcondusza/vale-styles/.vale.ini" +} \ No newline at end of file diff --git a/docs/cdp/cdp_activation/cdp_configuration.md b/docs/cdp/cdp_activation/cdp_configuration.md index efb4bdc429..4ee94683b4 100644 --- a/docs/cdp/cdp_activation/cdp_configuration.md +++ b/docs/cdp/cdp_activation/cdp_configuration.md @@ -17,20 +17,30 @@ ibexa: transport: stream_file stream_file: stream_id: 00000000-00000000-00000000-00000000 + content_data: + transport: stream_file + stream_file: + stream_id: 00000000-00000000-00000000-00000000 + product_data: + transport: stream_file + stream_file: + stream_id: 00000000-00000000-00000000-00000000 activations: - - client_id: '%env(CDP_ACTIVATION_CLIENT_ID)%' client_secret: '%env(CDP_ACTIVATION_CLIENT_SECRET)%' - segment_group_identifier: example_segment_group_identifier + segment_group_identifier: ibexa_cdp ``` -All configuration settings are described below. -You can follow them step by step to set up your [[= product_name_cdp =]]. +- **Account number** - can be obtained from Accounts settings in [[= product_name_cdp =]] dashboard +- **Stream ID** - use Stream ID generated during data import from "stream file" in Data Manager +- **Activations** - you can configure multiple activations, they have to be of type `[[= product_name_base =]]` in [[= product_name =]] dashboard +- **Client ID** and **Client secret** - Client ID and Secret pair is used to authenticate against Webhook endpoint, make sure it's random and secure +- **Segment group identifier** - is where CDP data is be imported to ## Segment group First, create a segment group in the Back Office. -It will serve as a container for all segments data generated by [[= product_name_cdp =]]. +It serve as a container for all segments data generated by [[= product_name_cdp =]]. Go to **Admin** -> **Segments** and select **Create**. Fill in name and identifier for a segment group. Choose wisely, as once connected to CDP Segment Group cannot be changed. diff --git a/docs/cdp/cdp_activation/cdp_data_export.md b/docs/cdp/cdp_activation/cdp_data_export.md index ecff4d1886..5a3c76443e 100644 --- a/docs/cdp/cdp_activation/cdp_data_export.md +++ b/docs/cdp/cdp_activation/cdp_data_export.md @@ -21,13 +21,27 @@ In the **Download** section, select **Stream file**. Copy generated steam ID and paste it into the configuration file under `stream_id`. It allows you to establish a datastream from the Streaming API into the Data Manager. -Next, you need to export your user data to the CDP. +Next, you need to export your data to the CDP. Go to your installation and use this command: +- user: + ```bash php bin/console ibexa:cdp:stream-user-data --draft ``` +- product: + +```bash +php bin/console ibexa:cdp:stream-product-data --draft +``` + +- content: + +```bash +php bin/console ibexa:cdp:stream-content-data --draft +``` + There are two versions of this command `--draft/--no-draft`. The first one is used to send the test user data to the Data Manager. If it passes a validation test in the **Activation** section, use the latter one to send a full version. From c892898f8d872717a046acbda2b905bcd8bb9416 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Fri, 13 Oct 2023 14:50:20 +0200 Subject: [PATCH 07/13] Fixes --- docs/cdp/cdp_activation/cdp_configuration.md | 2 +- docs/cdp/cdp_activation/cdp_data_export.md | 2 +- mkdocs.yml | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/cdp/cdp_activation/cdp_configuration.md b/docs/cdp/cdp_activation/cdp_configuration.md index 4ee94683b4..da44531045 100644 --- a/docs/cdp/cdp_activation/cdp_configuration.md +++ b/docs/cdp/cdp_activation/cdp_configuration.md @@ -1,5 +1,5 @@ --- -description: Step-by-step configuration procedure of [[= product_name_cdp =]] +description: Step-by-step configuration procedure of [[= product_name_cdp =]]. --- # Configuration diff --git a/docs/cdp/cdp_activation/cdp_data_export.md b/docs/cdp/cdp_activation/cdp_data_export.md index 5a3c76443e..a30dd8724c 100644 --- a/docs/cdp/cdp_activation/cdp_data_export.md +++ b/docs/cdp/cdp_activation/cdp_data_export.md @@ -1,5 +1,5 @@ --- -description: Step-by-step data export procedure of [[= product_name_cdp =]]. +description: Step-by-step data export procedure in [[= product_name_cdp =]]. --- # Data export diff --git a/mkdocs.yml b/mkdocs.yml index a03e3d5a9f..3e9c88cdc5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -408,7 +408,8 @@ nav: - CDP (Customer Data Platform): - Customer Data Platform: cdp/cdp.md - CDP installation: cdp/cdp_installation.md - - CDP activation: cdp/cdp_activation/cdp_activation.md + - CDP activation: + - CDP activation: cdp/cdp_activation/cdp_activation.md - CDP configuration: cdp/cdp_activation/cdp_configuration.md - CDP data export: cdp/cdp_activation/cdp_data_export.md - CDP add client-side tracking: cdp/cdp_activation/cdp_add_clientside_tracking.md From 0a4b57f355f11218ca4fd5c3b6679db05092157e Mon Sep 17 00:00:00 2001 From: julitafalcondusza <117284672+julitafalcondusza@users.noreply.github.com> Date: Tue, 31 Oct 2023 10:50:02 +0100 Subject: [PATCH 08/13] Delete .vscode/settings.json --- .vscode/settings.json | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index e553f50970..0000000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "vale.valeCLI.config": "/Users/julitafalcondusza/vale-styles/.vale.ini" -} \ No newline at end of file From 18d97852412cd11de430acf0e012e4668dba19c7 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Tue, 31 Oct 2023 11:15:41 +0100 Subject: [PATCH 09/13] Fixes after review --- docs/cdp/cdp_activation/cdp_configuration.md | 6 +++--- docs/cdp/cdp_activation/cdp_data_export.md | 14 +++++++------- ..._extension.md => cdp_data_customization.md} | 6 +++--- docs/cdp/cdp_data_export_schedule.md | 18 ++++++++++++++++-- mkdocs.yml | 2 +- 5 files changed, 30 insertions(+), 16 deletions(-) rename docs/cdp/{cdp_data_extension.md => cdp_data_customization.md} (95%) diff --git a/docs/cdp/cdp_activation/cdp_configuration.md b/docs/cdp/cdp_activation/cdp_configuration.md index da44531045..b89dd730ac 100644 --- a/docs/cdp/cdp_activation/cdp_configuration.md +++ b/docs/cdp/cdp_activation/cdp_configuration.md @@ -45,7 +45,7 @@ Go to **Admin** -> **Segments** and select **Create**. Fill in name and identifier for a segment group. Choose wisely, as once connected to CDP Segment Group cannot be changed. -![Creating a new segment group](img/cdp_create_segment_group.png) +![Creating a new segment group](cdp_create_segment_group.png) Next, add a segment group identifier to the configuration. @@ -58,8 +58,8 @@ Next, add a segment group identifier to the configuration. Now, fill in the account number. Log in to [[= product_name_cdp =]] and in the top right corner, select available accounts. -![List of available accounts](img/cdp_accounts.png) +![List of available accounts](cdp_accounts.png) A pop-up window displays with a list of all available accounts and their numbers. -![Account number](img/cdp_account_number.png) +![Account number](cdp_account_number.png) diff --git a/docs/cdp/cdp_activation/cdp_data_export.md b/docs/cdp/cdp_activation/cdp_data_export.md index a30dd8724c..972e73b09d 100644 --- a/docs/cdp/cdp_activation/cdp_data_export.md +++ b/docs/cdp/cdp_activation/cdp_data_export.md @@ -24,19 +24,19 @@ It allows you to establish a datastream from the Streaming API into the Data Man Next, you need to export your data to the CDP. Go to your installation and use this command: -- user: +- for User: ```bash php bin/console ibexa:cdp:stream-user-data --draft ``` -- product: +- for Product: ```bash php bin/console ibexa:cdp:stream-product-data --draft ``` -- content: +- for Content: ```bash php bin/console ibexa:cdp:stream-content-data --draft @@ -68,11 +68,11 @@ Next, select **Create schema based on the downloaded columns**. It will move you to Schema Creator. There, choose **PersonalData** as a parent and name the schema. -![Create new schema](img/cdp_create_new_schema.png) +![Create new schema](cdp_create_new_schema.png) Next, select all the columns and set Person Identifier as **userid**. -![Person Identifier](img/cdp_person_identifier.png) +![Person Identifier](cdp_person_identifier.png) If you used PersonData or Catalog type schemas, the system will require specifying the Write Mode that will be applied to them. @@ -116,7 +116,7 @@ You can configure multiple activations based data flows. First, from the menu bar, select **Activations** and create a new **Ibexa** activation. Specify name of your activation, select `userid` as **Person Identifier** and click **Next**. -![General Information - Activation](img/cdp_activation_general_info.png) +![General Information - Activation](cdp_activation_general_info.png) Next, you can fill in **Ibexa information** they must match the ones provided in the YAML configuration: @@ -125,7 +125,7 @@ Next, you can fill in **Ibexa information** they must match the ones provided in - **Segment Group Identifier** - identifier of the segment group in [[= product_name =]]. It points to a segment group where all the CDP audiences will be stored. - **Base URL** - URL of your instance with added `/cdp/webhook` at the end. -![Ibexa Information - Activation](img/cdp_activation_ibexa_info.png) +![Ibexa Information - Activation](cdp_activation_ibexa_info.png) Finally, you can specify the audiences you wish to include. diff --git a/docs/cdp/cdp_data_extension.md b/docs/cdp/cdp_data_customization.md similarity index 95% rename from docs/cdp/cdp_data_extension.md rename to docs/cdp/cdp_data_customization.md index b6fc8cb884..1c68be32ef 100644 --- a/docs/cdp/cdp_data_extension.md +++ b/docs/cdp/cdp_data_customization.md @@ -1,10 +1,10 @@ --- -description: Data extension in [[= product_name_cdp =]]. +description: Data customization in [[= product_name_cdp =]]. --- -# Data extension +# Data customization ​ -You can customize Content, User and Product data exported to CDP and you can control what Field Type information you want to export. +You can customize Content and Product data exported to CDP and you can control what Field Type information you want to export. By default, custom Field Types have basic export functionality. It casts their `Value` object to string, thanks to `\Stringable` implementation. ​ ## Exporting Field Types diff --git a/docs/cdp/cdp_data_export_schedule.md b/docs/cdp/cdp_data_export_schedule.md index 5f91a04bdf..4705c8111c 100644 --- a/docs/cdp/cdp_data_export_schedule.md +++ b/docs/cdp/cdp_data_export_schedule.md @@ -43,10 +43,24 @@ Structure of each section is exactly the same and includes `interval` and `optio It uses standard `crontab` format (see: https://crontab.guru/examples.html). - **Options** - allows you to add arguments that have to be passed to the export command. -This configuration allows you to provide multiple export tools with parameters. It's important, because each type of content/product must have its own parameters on the CDP website, where each has a different Stream ID key and different required values, for example, `--content-type`. +This configuration allows you to provide multiple export workflows with parameters. It's important, because each type of content/product must have its own parameters on the CDP side, where each has a different Stream ID key and different required values, which are configured per data source. -Accepted options can be listed with this command: +Accepted options can be listed with the command below: + +* for User: ```bash php bin/console ibexa:cdp:stream-user-data --help +``` + +* for Product: + +```bash +php bin/console ibexa:cdp:stream-product-data --help +``` + +* for Content: + +```bash +php bin/console ibexa:cdp:stream-content-data --help ``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 3e9c88cdc5..026257a2df 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -414,7 +414,7 @@ nav: - CDP data export: cdp/cdp_activation/cdp_data_export.md - CDP add client-side tracking: cdp/cdp_activation/cdp_add_clientside_tracking.md - CDP data export schedule: cdp/cdp_data_export_schedule.md - - CDP data export: cdp/cdp_data_extension.md + - CDP data customization: cdp/cdp_data_customization.md - Search: - Search: search/search.md - Search engines: From 12a0b5713764ed4334c45a00f400eafa6e0cef36 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Tue, 31 Oct 2023 11:20:48 +0100 Subject: [PATCH 10/13] Img path fixed --- docs/cdp/cdp_activation/cdp_data_export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cdp/cdp_activation/cdp_data_export.md b/docs/cdp/cdp_activation/cdp_data_export.md index 972e73b09d..416b176ab3 100644 --- a/docs/cdp/cdp_activation/cdp_data_export.md +++ b/docs/cdp/cdp_activation/cdp_data_export.md @@ -84,7 +84,7 @@ For example, if a customer unsubscribes a newsletter, their email will remain in Next, select **userid** from a **Schema columns section** on the right and map it to **id**. -![Map userid to id](img/cdp_userid_mapid.png) +![Map userid to id](cdp_userid_mapid.png) ## Activation From 5586e94b7f953a3191b5d5dea639fabf57a0a979 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Tue, 31 Oct 2023 11:55:57 +0100 Subject: [PATCH 11/13] Vale fixes --- docs/cdp/cdp_data_customization.md | 12 +++++++----- docs/cdp/cdp_data_export_schedule.md | 2 +- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/cdp/cdp_data_customization.md b/docs/cdp/cdp_data_customization.md index 1c68be32ef..da23674775 100644 --- a/docs/cdp/cdp_data_customization.md +++ b/docs/cdp/cdp_data_customization.md @@ -5,7 +5,7 @@ description: Data customization in [[= product_name_cdp =]]. # Data customization ​ You can customize Content and Product data exported to CDP and you can control what Field Type information you want to export. -By default, custom Field Types have basic export functionality. It casts their `Value` object to string, thanks to `\Stringable` implementation. +By default, custom Field Types have basic export functionality. It casts their `Value` object to string, thanks to `\Stringable` implementation. ​ ## Exporting Field Types ​ @@ -38,7 +38,7 @@ Field identifier is a prefix that is automatically added to each key. You can on ​ ### Built in Field Processors for custom Field Types ​ -You may provide your own CDP export functionality by using one of the system Field Processors: +You may provide your own CDP export functionality by using one of the system Field Processors: #### `\Ibexa\Cdp\Export\Content\FieldProcessor\SkippingFieldProcessor`. ​ @@ -57,11 +57,13 @@ custom_fieldtype.cdp.export.field_processor: ​ ## Exporting Field Type values ​ -To customize export of Field Type values, provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldValueProcessorInterface` instance. +To customize export of Field Type values, provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldValueProcessorInterface` instance. YNew implementation has to be registered as a service manually or by using autoconfiguration. The service has to use the tag `ibexa.cdp.export.content.field_value_processor`, you can also provide `priority` property to override other Field Value Processors. ​ -* `FieldValueProcessorInterface::process` - takes `Field` instance and returns an `array` with scalar values that are applied to export data payload. If th Field Type returns single value, provide `value` key in the array. You can return multiple values. -* `FieldValueProcessorInterface::supports` - decides whether `FieldValueProcessor` can work with the `Field`. +* `FieldValueProcessorInterface::process` - takes `Field` instance and returns an `array` with scalar values that are applied to export data payload. +If the Field Type returns single value, provide `value` key in the array. You can return multiple values. + +* `FieldValueProcessorInterface::supports` - decides whether `FieldValueProcessor` can work with the `Field`. ​ ### Built in Field Value Processors for custom Field Types ​ diff --git a/docs/cdp/cdp_data_export_schedule.md b/docs/cdp/cdp_data_export_schedule.md index 4705c8111c..dcb757d2bc 100644 --- a/docs/cdp/cdp_data_export_schedule.md +++ b/docs/cdp/cdp_data_export_schedule.md @@ -39,7 +39,7 @@ ibexa_cdp: Under `schedule` setting you can find separate sections for exporting User, Content, and Product. Structure of each section is exactly the same and includes `interval` and `options` elements: -- **Interval** - sets the frequency of the command invoke, for example, '*/30 * * * *' - every 30 minutes, '0 */12 * * *' - every 12 hours. +- **Interval** - sets the frequency of the command invoke, for example, '*/30 * * * *' - every 30 minutes, '0 */12 * * *' - every 12 hours. It uses standard `crontab` format (see: https://crontab.guru/examples.html). - **Options** - allows you to add arguments that have to be passed to the export command. From 6335a5e5c4d3b28741124ad7370e942554284af1 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Wed, 8 Nov 2023 12:04:19 +0100 Subject: [PATCH 12/13] Fixes after review --- docs/cdp/cdp_activation/cdp_activation.md | 6 ++++-- .../cdp_activation/cdp_add_clientside_tracking.md | 2 +- docs/cdp/cdp_activation/cdp_configuration.md | 10 +++++----- docs/cdp/cdp_activation/cdp_data_export.md | 2 +- docs/cdp/cdp_data_customization.md | 15 ++++++++++----- docs/cdp/cdp_data_export_schedule.md | 4 ++-- 6 files changed, 23 insertions(+), 16 deletions(-) diff --git a/docs/cdp/cdp_activation/cdp_activation.md b/docs/cdp/cdp_activation/cdp_activation.md index 7ff878e6a3..ffdb9278e6 100644 --- a/docs/cdp/cdp_activation/cdp_activation.md +++ b/docs/cdp/cdp_activation/cdp_activation.md @@ -1,12 +1,14 @@ --- -description: Step-by-step activation procedure of [[= product_name_cdp =]]. +description: Step-by-step activation procedure of Ibexa CDP. page_type: landing_page --- -# Administration +# Adctivation Follow step-by-step activation procedure of [[= product_name_cdp =]]. +Activation includes configuration, data export and adding Client-side Tracking. + [[= cards([ "cdp/cdp_activation/cdp_configuration", "cdp/cdp_activation/cdp_data_export", diff --git a/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md b/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md index 19cd699b75..7a5403d63a 100644 --- a/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md +++ b/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md @@ -1,5 +1,5 @@ --- -description: Client-side Tracking in [[= product_name_cdp =]]. +description: Client-side Tracking in Ibexa CDP. --- # Add Client-side Tracking diff --git a/docs/cdp/cdp_activation/cdp_configuration.md b/docs/cdp/cdp_activation/cdp_configuration.md index b89dd730ac..27d098c07e 100644 --- a/docs/cdp/cdp_activation/cdp_configuration.md +++ b/docs/cdp/cdp_activation/cdp_configuration.md @@ -1,5 +1,5 @@ --- -description: Step-by-step configuration procedure of [[= product_name_cdp =]]. +description: Step-by-step configuration procedure of Ibexa CDP. --- # Configuration @@ -33,14 +33,14 @@ ibexa: - **Account number** - can be obtained from Accounts settings in [[= product_name_cdp =]] dashboard - **Stream ID** - use Stream ID generated during data import from "stream file" in Data Manager -- **Activations** - you can configure multiple activations, they have to be of type `[[= product_name_base =]]` in [[= product_name =]] dashboard +- **Activations** - you can configure multiple activations, they have to be of type `Ibexa` in [[= product_name =]] dashboard - **Client ID** and **Client secret** - Client ID and Secret pair is used to authenticate against Webhook endpoint, make sure it's random and secure -- **Segment group identifier** - is where CDP data is be imported to +- **Segment group identifier** - is the location where CDP data is imported ## Segment group First, create a segment group in the Back Office. -It serve as a container for all segments data generated by [[= product_name_cdp =]]. +It serves as a container for all segments data generated by [[= product_name_cdp =]]. Go to **Admin** -> **Segments** and select **Create**. Fill in name and identifier for a segment group. Choose wisely, as once connected to CDP Segment Group cannot be changed. @@ -60,6 +60,6 @@ Log in to [[= product_name_cdp =]] and in the top right corner, select available ![List of available accounts](cdp_accounts.png) -A pop-up window displays with a list of all available accounts and their numbers. +A pop-up window displays a list of all available accounts and their numbers. ![Account number](cdp_account_number.png) diff --git a/docs/cdp/cdp_activation/cdp_data_export.md b/docs/cdp/cdp_activation/cdp_data_export.md index 416b176ab3..e7e8fca271 100644 --- a/docs/cdp/cdp_activation/cdp_data_export.md +++ b/docs/cdp/cdp_activation/cdp_data_export.md @@ -1,5 +1,5 @@ --- -description: Step-by-step data export procedure in [[= product_name_cdp =]]. +description: Step-by-step data export procedure in Ibexa CDP. --- # Data export diff --git a/docs/cdp/cdp_data_customization.md b/docs/cdp/cdp_data_customization.md index da23674775..2e54e30d58 100644 --- a/docs/cdp/cdp_data_customization.md +++ b/docs/cdp/cdp_data_customization.md @@ -1,5 +1,5 @@ --- -description: Data customization in [[= product_name_cdp =]]. +description: Data customization in Ibexa CDP. --- # Data customization @@ -9,7 +9,11 @@ By default, custom Field Types have basic export functionality. It casts their ` ​ ## Exporting Field Types ​ -Field Types are exported with metadata, for example, ID, Field Definition name, type, value. You can also provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldProcessorInterface` instance to extend metadata. Provided implementation has to be defined as a service and tagged with `ibexa.cdp.export.content.field_processor`. Additionally, you can specify `priority` to override default behavior. All system Field Processors use `-100` priority, and any higher priority value overrides them. +Field Types are exported with metadata, for example, ID, Field Definition name, type, value. +You can also provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldProcessorInterface` instance to extend metadata. +Provided implementation has to be defined as a service and tagged with `ibexa.cdp.export.content.field_processor`. +Additionally, you can specify `priority` to override default behavior. +All system Field Processors use `-100` priority, and any higher priority value overrides them. The interface is plain and has two methods that you need to provide: @@ -58,16 +62,17 @@ custom_fieldtype.cdp.export.field_processor: ## Exporting Field Type values ​ To customize export of Field Type values, provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldValueProcessorInterface` instance. -YNew implementation has to be registered as a service manually or by using autoconfiguration. The service has to use the tag `ibexa.cdp.export.content.field_value_processor`, you can also provide `priority` property to override other Field Value Processors. +New implementation has to be registered as a service manually or by using autoconfiguration. +The service has to use the tag `ibexa.cdp.export.content.field_value_processor`, you can also provide `priority` property to override other Field Value Processors. ​ * `FieldValueProcessorInterface::process` - takes `Field` instance and returns an `array` with scalar values that are applied to export data payload. -If the Field Type returns single value, provide `value` key in the array. You can return multiple values. +If the Field Type returns single value, provided `value` key in the array. You can return multiple values. * `FieldValueProcessorInterface::supports` - decides whether `FieldValueProcessor` can work with the `Field`. ​ ### Built in Field Value Processors for custom Field Types ​ -There are few system Field Value Processors that either work by default or can be registered for custom Field Types: +Several system Field Value Processors either work by default or can be registered for custom Field Types: ​ #### `\Ibexa\Cdp\Export\Content\FieldValueProcessor\CastToStringFieldValueProcessor` ​ diff --git a/docs/cdp/cdp_data_export_schedule.md b/docs/cdp/cdp_data_export_schedule.md index dcb757d2bc..9ee6522361 100644 --- a/docs/cdp/cdp_data_export_schedule.md +++ b/docs/cdp/cdp_data_export_schedule.md @@ -1,5 +1,5 @@ --- -description: Data export schedule in [[= product_name_cdp =]]. +description: Data export schedule in Ibexa CDP. --- # CDP data export schedule @@ -40,7 +40,7 @@ Under `schedule` setting you can find separate sections for exporting User, Cont Structure of each section is exactly the same and includes `interval` and `options` elements: - **Interval** - sets the frequency of the command invoke, for example, '*/30 * * * *' - every 30 minutes, '0 */12 * * *' - every 12 hours. -It uses standard `crontab` format (see: https://crontab.guru/examples.html). +It uses standard `crontab` format, see [examples](https://crontab.guru/examples.html). - **Options** - allows you to add arguments that have to be passed to the export command. This configuration allows you to provide multiple export workflows with parameters. It's important, because each type of content/product must have its own parameters on the CDP side, where each has a different Stream ID key and different required values, which are configured per data source. From a1ce3ca54b2a36e9ae41a78bc4c17ae640ea6e46 Mon Sep 17 00:00:00 2001 From: julitafalcondusza Date: Mon, 13 Nov 2023 15:44:15 +0100 Subject: [PATCH 13/13] Fixes --- docs/cdp/cdp_activation/cdp_activation.md | 4 +- .../cdp_add_clientside_tracking.md | 12 +++--- docs/cdp/cdp_activation/cdp_configuration.md | 38 +++++++++---------- docs/cdp/cdp_data_customization.md | 26 +++++++------ docs/cdp/cdp_data_export_schedule.md | 11 +++--- 5 files changed, 48 insertions(+), 43 deletions(-) diff --git a/docs/cdp/cdp_activation/cdp_activation.md b/docs/cdp/cdp_activation/cdp_activation.md index ffdb9278e6..fb8962455f 100644 --- a/docs/cdp/cdp_activation/cdp_activation.md +++ b/docs/cdp/cdp_activation/cdp_activation.md @@ -3,9 +3,9 @@ description: Step-by-step activation procedure of Ibexa CDP. page_type: landing_page --- -# Adctivation +# CDP Activation -Follow step-by-step activation procedure of [[= product_name_cdp =]]. +Follow a step-by-step procedure that allows you to activate [[= product_name_cdp =]]. Activation includes configuration, data export and adding Client-side Tracking. diff --git a/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md b/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md index 7a5403d63a..22a01f659b 100644 --- a/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md +++ b/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md @@ -5,17 +5,17 @@ description: Client-side Tracking in Ibexa CDP. # Add Client-side Tracking The final step is setting up a tracking script. -It requires a head tracking script between the `` tags on your website -and a main script after the head script, and cookie consent. -You can do it by following [tutorial in the documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/115000656909-Client-side-Tracking). +It requires a head tracking script between the `` tags on your website, +a main script after the head script, and cookie consent. +For more information about setting up a tracking script, see [a tutorial in Raptor documentation](https://support.raptorsmartadvisor.com/hc/en-us/articles/9563346335004-Client-Side-Tracking). Now, you need to add a tracker to specific places in your website where you want to track users. -For example, add this tracker to the Landing Page template if you want to track user entrances. +For example, add this tracker to the Landing Page template to track user entrances. ```js raptor.trackEvent('visit', ..., ...); ``` -or buys: +or purchases: ```js //Parameters for Product 1 @@ -24,7 +24,7 @@ raptor.trackEvent('buy', ..., ...); raptor.trackEvent('buy', ..., ...); ``` -For tracing to be effective, you also need to send ID of a logged-in user in the same way. +For tracking to be effective, you also need to send ID of a logged-in user in the same way. Add the user ID information by using below script: ```js diff --git a/docs/cdp/cdp_activation/cdp_configuration.md b/docs/cdp/cdp_activation/cdp_configuration.md index 27d098c07e..9c50f36350 100644 --- a/docs/cdp/cdp_activation/cdp_configuration.md +++ b/docs/cdp/cdp_activation/cdp_configuration.md @@ -31,35 +31,35 @@ ibexa: segment_group_identifier: ibexa_cdp ``` -- **Account number** - can be obtained from Accounts settings in [[= product_name_cdp =]] dashboard -- **Stream ID** - use Stream ID generated during data import from "stream file" in Data Manager -- **Activations** - you can configure multiple activations, they have to be of type `Ibexa` in [[= product_name =]] dashboard -- **Client ID** and **Client secret** - Client ID and Secret pair is used to authenticate against Webhook endpoint, make sure it's random and secure -- **Segment group identifier** - is the location where CDP data is imported +- `account_number` - a [number](#account-number) obtained from Accounts settings in [[= product_name_cdp =]] dashboard +- `stream_id` - stream ID generated when importing data from the stream file in Data Manage +- `activations` - activation details. You can configure multiple activations. They have to be of type `Ibexa` in [[= product_name =]] dashboard +- `client_id` and `client_secret` - client credentials are used to authenticate against the Webhook endpoint. Make sure they are random and secure +- `segment_group_identifier` - a [location](#segment-group) to which CDP data is imported + +## Account number + +Now, fill in the account number. +Log in to [[= product_name_cdp =]] and in the top right corner, select available accounts. + +![List of available accounts](cdp_accounts.png) + +A pop-up window displays a list of all available accounts and their numbers. + +![Account number](cdp_account_number.png) ## Segment group -First, create a segment group in the Back Office. +Create a segment group in the Back Office. It serves as a container for all segments data generated by [[= product_name_cdp =]]. Go to **Admin** -> **Segments** and select **Create**. Fill in name and identifier for a segment group. Choose wisely, as once connected to CDP Segment Group cannot be changed. -![Creating a new segment group](cdp_create_segment_group.png) - -Next, add a segment group identifier to the configuration. - !!! caution "[[= product_name_cdp =]] Segment Group" After you create the Segment Group in the Back Office and connect it to [[= product_name_cdp =]], you cannot change it in any way, including edit its name. -## Account number - -Now, fill in the account number. -Log in to [[= product_name_cdp =]] and in the top right corner, select available accounts. - -![List of available accounts](cdp_accounts.png) - -A pop-up window displays a list of all available accounts and their numbers. +![Creating a new segment group](cdp_create_segment_group.png) -![Account number](cdp_account_number.png) +Next, add a segment group identifier to the configuration. diff --git a/docs/cdp/cdp_data_customization.md b/docs/cdp/cdp_data_customization.md index 2e54e30d58..831dcdaafe 100644 --- a/docs/cdp/cdp_data_customization.md +++ b/docs/cdp/cdp_data_customization.md @@ -5,14 +5,15 @@ description: Data customization in Ibexa CDP. # Data customization ​ You can customize Content and Product data exported to CDP and you can control what Field Type information you want to export. -By default, custom Field Types have basic export functionality. It casts their `Value` object to string, thanks to `\Stringable` implementation. +By default, custom Field Types have basic export functionality. +It casts their `Value` object to string, thanks to `\Stringable` implementation. ​ -## Exporting Field Types +## Export Field Types ​ Field Types are exported with metadata, for example, ID, Field Definition name, type, value. -You can also provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldProcessorInterface` instance to extend metadata. -Provided implementation has to be defined as a service and tagged with `ibexa.cdp.export.content.field_processor`. -Additionally, you can specify `priority` to override default behavior. +You can also provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldProcessorInterface` instance to extend metadata. +The provided implementation has to be defined as a service and tagged with `ibexa.cdp.export.content.field_processor`. +Additionally, you can specify `priority` to override the default behavior. All system Field Processors use `-100` priority, and any higher priority value overrides them. The interface is plain and has two methods that you need to provide: @@ -38,16 +39,17 @@ A common Field Type is serialized to: } ``` ​ -Field identifier is a prefix that is automatically added to each key. You can only use scalar values. +Field identifier is a prefix that is automatically added to each key. +You can only use scalar values. ​ ### Built in Field Processors for custom Field Types ​ -You may provide your own CDP export functionality by using one of the system Field Processors: +You can provide your own CDP export functionality by using one of the system Field Processors: #### `\Ibexa\Cdp\Export\Content\FieldProcessor\SkippingFieldProcessor`. ​ It results in the Field Type being excluded from the exported payload. -To avoid adding the Field Type data to the payload, register a new service as follow: +To avoid adding the Field Type data to the payload, register a new service as follows: ​ ```yaml custom_fieldtype.cdp.export.field_processor: @@ -59,14 +61,16 @@ custom_fieldtype.cdp.export.field_processor: - { name: 'ibexa.cdp.export.content.field_processor', priority: 0 } ``` ​ -## Exporting Field Type values +## Export Field Type values ​ To customize export of Field Type values, provide your own `\Ibexa\Contracts\Cdp\Export\Content\FieldValueProcessorInterface` instance. New implementation has to be registered as a service manually or by using autoconfiguration. -The service has to use the tag `ibexa.cdp.export.content.field_value_processor`, you can also provide `priority` property to override other Field Value Processors. +The service has to use the tag `ibexa.cdp.export.content.field_value_processor`. +You can also provide `priority` property to override other Field Value Processors. ​ * `FieldValueProcessorInterface::process` - takes `Field` instance and returns an `array` with scalar values that are applied to export data payload. -If the Field Type returns single value, provided `value` key in the array. You can return multiple values. +If the Field Type returns a single value, provides a `value` key in the array. +You can return multiple values. * `FieldValueProcessorInterface::supports` - decides whether `FieldValueProcessor` can work with the `Field`. ​ diff --git a/docs/cdp/cdp_data_export_schedule.md b/docs/cdp/cdp_data_export_schedule.md index 9ee6522361..b7b5c9c6f3 100644 --- a/docs/cdp/cdp_data_export_schedule.md +++ b/docs/cdp/cdp_data_export_schedule.md @@ -7,7 +7,7 @@ description: Data export schedule in Ibexa CDP. ## Configuration key Configuration in [[= product_name_cdp =]] allows you to automate the process of exporting Content, Users and Products. -Global `ibexa_cdp` [configuration key](configuration.md#configuration-files) looks as below: +A global `ibexa_cdp` [configuration key](configuration.md#configuration-files) looks as below: ```yaml ibexa_cdp: @@ -36,14 +36,15 @@ ibexa_cdp: options: '--stream-id=00000000-00000000-00000000-00000000 --product-type=computer --no-draft' ``` -Under `schedule` setting you can find separate sections for exporting User, Content, and Product. +Under the `schedule` setting you can find separate sections for exporting User, Content, and Product. Structure of each section is exactly the same and includes `interval` and `options` elements: -- **Interval** - sets the frequency of the command invoke, for example, '*/30 * * * *' - every 30 minutes, '0 */12 * * *' - every 12 hours. -It uses standard `crontab` format, see [examples](https://crontab.guru/examples.html). +- **Interval** - sets the frequency of the command invoke, for example, '*/30 * * * *' means "every 30 minutes", '0 */12 * * *' means "every 12 hours". +It uses a standard `crontab` format, see [examples](https://crontab.guru/examples.html). - **Options** - allows you to add arguments that have to be passed to the export command. -This configuration allows you to provide multiple export workflows with parameters. It's important, because each type of content/product must have its own parameters on the CDP side, where each has a different Stream ID key and different required values, which are configured per data source. +This configuration allows you to provide multiple export workflows with parameters. +It's important, because each type of content/product must have its own parameters on the CDP side, where each has a different Stream ID key and different required values, which are configured per data source. Accepted options can be listed with the command below: