• Documentation >
• Recommendations >
• Integration with Raptor >
• Installation and configuration

Configuration procedure

To configure the Raptor integration, follow a step-by-step procedure that allows you to activate the Raptor connector.

Installation

First, install the Raptor connector. To do it, run the following command:

composer require ibexa/connector-raptor

SiteAccess-aware configuration

To configure Raptor connector, use the ibexa.system.<scope>.connector_raptor configuration key in the config/packages/ibexa_connector_raptor.yaml file:

    system:
        <scope>:
            connector_raptor:
                enabled:              true
                customer_id:          ~ # Required
                tracking_type:        client # One of: "client" or "server"

                # Raptor Recommendations API key
                recommendations_api_key: ~ # Required

                # Raptor Recommendations API URL, optional, set by default
                recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%'
ibexa_connector_raptor:

• enabled - enables or disables the Connector for a given scope, default value: true. If set to false, no tracking or recommendation requests are executed.
• customer_id - an identifier used to authenticate requests to the Recommendation Engine. This value can be found as Account number in Raptor Control Panel.
• tracking_type - defines how user events are sent to the tracking API. Default value: client. Possible values:
  • client - tracking is executed in the browser using JavaScript snippets generated by Twig functions and included in templates. This approach may be blocked by ad blockers.
  • server - tracking is handled on the backend, with events sent directly to the tracking API. It's not affected by ad blockers.
• recommendations_api_key - an API key used to authenticate requests to the Recommendations API. This key allows the Connector to retrieve personalized recommendations from the Recommendation Engine. This value can be found as API key in Raptor Control Panel.
• recommendations_api_url (optional) - overrides the default Raptor address, should be left unset unless a custom endpoint is required.

By default, tracking_type is set to client as client-side tracking is the standard Raptor mode. To understand the differences between client and server tracking types, including their advantages and disadvantages, refer to the Raptor documentation.

Note

Only one tracking mode can be enabled at a time. Client-side and server-side tracking cannot be used together.

Customer ID

To find the value for the customer_id identifier, log in to Raptor Control Panel, and look for "Account number":

A. In the top-left corner, above the account name, you can find the account number for the currently active account. B. Click the arrow icon in the top-left corner to expand the window. There you can see a list of all your accounts, with their numbers shown in the “Account number” column on the right (if you have multiple accounts, you can easily locate and copy the number of any of your accounts, not just the active one).

Recommendations API key

To find the value for the recommendations_api_key, log in to Raptor Control Panel, and look for "API key". To do it, in the left panel, open the Recommendations section, and select Website. Next, click on the Web module you’re interested in. In the top-right corner, click the three-dot icon and select API information. A new window appears, where you can find the "API key" value. Click on the Show API information and copy the value.

Global configuration (non-SiteAccess-aware)

The following settings are global and apply to the entire application (they are not scoped per SiteAccess):

• strict_exceptions – when enabled, tracking exceptions are thrown instead of being silently handled. Default value: %kernel.debug%.

This value can be overriden in config/packages/ibexa_connector_raptor.yaml file, for example:

ibexa:
    system:
        <scope>:
            connector_raptor:
                enabled:              true
                customer_id:          ~ # Required
                tracking_type:        client # One of: "client" or "server"

                # Raptor Recommendations API key
                recommendations_api_key: ~ # Required

                # Raptor Recommendations API URL, optional, set by default
                recommendations_api_url: '%ibexa.connector.raptor.recommendations.api_url%'
ibexa_connector_raptor:
    # When enabled, tracking exceptions are thrown instead of being silently handled
    strict_exceptions: true