diff --git a/docs/cdp/cdp_activation/cdp_activation.md b/docs/cdp/cdp_activation/cdp_activation.md new file mode 100644 index 0000000000..fb8962455f --- /dev/null +++ b/docs/cdp/cdp_activation/cdp_activation.md @@ -0,0 +1,16 @@ +--- +description: Step-by-step activation procedure of Ibexa CDP. +page_type: landing_page +--- + +# CDP Activation + +Follow a step-by-step procedure that allows you to activate [[= 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", + "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..22a01f659b --- /dev/null +++ b/docs/cdp/cdp_activation/cdp_add_clientside_tracking.md @@ -0,0 +1,34 @@ +--- +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, +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 to track user entrances. + +```js +raptor.trackEvent('visit', ..., ...); +``` +or purchases: + +```js + //Parameters for Product 1 +raptor.trackEvent('buy', ..., ...); + //Parameters for Product 2 +raptor.trackEvent('buy', ..., ...); +``` + +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 +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..9c50f36350 --- /dev/null +++ b/docs/cdp/cdp_activation/cdp_configuration.md @@ -0,0 +1,65 @@ +--- +description: Step-by-step configuration procedure of Ibexa 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 + 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: ibexa_cdp +``` + +- `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 + +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. + +!!! 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. + +![Creating a new segment group](cdp_create_segment_group.png) + +Next, add a segment group identifier to the configuration. diff --git a/docs/cdp/cdp_activation.md b/docs/cdp/cdp_activation/cdp_data_export.md similarity index 57% rename from docs/cdp/cdp_activation.md rename to docs/cdp/cdp_activation/cdp_data_export.md index 0156b3a423..e7e8fca271 100644 --- a/docs/cdp/cdp_activation.md +++ b/docs/cdp/cdp_activation/cdp_data_export.md @@ -1,87 +1,47 @@ --- -description: Step-by-step activation procedure of Ibexa CDP. +description: Step-by-step data export procedure in Ibexa 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`. 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: +- for User: + ```bash php bin/console ibexa:cdp:stream-user-data --draft ``` +- for Product: + +```bash +php bin/console ibexa:cdp:stream-product-data --draft +``` + +- for 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. @@ -90,7 +50,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 +59,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. @@ -108,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. @@ -124,9 +84,9 @@ 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 +## 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 +97,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. @@ -156,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: @@ -165,41 +125,10 @@ 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. !!! 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_customization.md b/docs/cdp/cdp_data_customization.md new file mode 100644 index 0000000000..831dcdaafe --- /dev/null +++ b/docs/cdp/cdp_data_customization.md @@ -0,0 +1,103 @@ +--- +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. +​ +## 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. +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: + +- **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 common Field Type is 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 +} +``` +​ +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 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 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 } +``` +​ +## 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. +​ +* `FieldValueProcessorInterface::process` - takes `Field` instance and returns an `array` with scalar values that are applied to export data payload. +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`. +​ +### Built in Field Value Processors 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` +​ +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` +​ +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: + 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_data_export_schedule.md b/docs/cdp/cdp_data_export_schedule.md new file mode 100644 index 0000000000..b7b5c9c6f3 --- /dev/null +++ b/docs/cdp/cdp_data_export_schedule.md @@ -0,0 +1,67 @@ +--- +description: Data export schedule in Ibexa CDP. +--- + +# CDP data export schedule + +## Configuration key + +Configuration in [[= product_name_cdp =]] allows you to automate the process of exporting Content, Users and Products. +A global `ibexa_cdp` [configuration key](configuration.md#configuration-files) looks as below: + +```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' +``` + +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 * * * *' 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. + +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 897d4513b7..026257a2df 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -408,7 +408,13 @@ 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 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 customization: cdp/cdp_data_customization.md - Search: - Search: search/search.md - Search engines: