SAP Hybris Profile

Overview

SAP Hybris Profile allows businesses to create, maintain, and continually extend customer profiles from a range of data sources. The SAP Hybris Profile platform is extensible and leverages a schema-less data structure to allow the capture of new data and insights to enrich and extend customer profiles. Consuming applications benefit from rich, contextually consistent and relevant representations of customers that evolve over time.

In the first release of SAP Hybris Profile, data capture and processing focuses on Enterprise Commerce Platform (ECP) and YaaS storefront commerce data. The image shown here illustrates the different types of data sources used when you extend SAP Hybris Profile on a project basis.

Customer Profile Overview

A customer profile is a collection of attributes, conclusions, and classifications about a customer. These are derived from customer interactions with the company.

SAP Hybris Profile attributes include:

  • Commerce-related scenarios
  • Product, category, and brand affinities
  • Purchase history
  • Browsing history
  • Browsing behavior, including basic behavioral attributes
  • Technical attributes and classifications, such as device and browser-specific attributes

Responsible data management is the key to trust, so a guarantee of data privacy is paramount. In SAP Hybris Profile, customer data cannot be collected or used without consent from the customer. Using SAP Hybris Profile's optional consent services, the brand or store owner exposes consent management to customers at any level of data granularity, from global control to fine-grained control of particular data types and sources. See the Manage Consent topic for details.

Data transparency

There are many creative ways that you can present profile data to a customer. You can customize displays to best serve each industry and business model. For example, a brick-and-mortar store can emphasize geographic location, a clothing store can focus on color schemes, and an online outlet can display product-buying history, patterns, brand affinity, or feature preferences. Below are samples of different ways to display profile data to a customer:

Profile Transparency

Partner integration and extensibility

As an SAP Hybris partner, augment the SAP Hybris Profile system with custom-developed extensions that capture and interpret profile data to optimize customer service and business efficiency. SAP Hybris Profile leverages YaaS' unique extensibility concept for partners to customize their solutions, and to offer new services for sale on the YaaS Market so that other companies can leverage them.

If an entry point for particular customer data is lacking, extend the product and add that entry point. For example, to add a customer's Instagram data to SAP Hybris Profile, you can write and submit a new service to collect that data. Extensions can also analyze existing data to find new patterns and draw new conclusions. For example, a new service could analyze product-view history and conclude that a customer has an affinity for button-down dress shirts with stripes. Other applications can use that analysis to enhance customer service and send the customer online coupons for these types of shirts.

Consent requirements apply to any new data collected by partner-developed services.


Profile Structure

SAP Hybris Profile uses a graph database to store each customer's profile, sessions, interactions, insights, and other relevant data. In contrast to traditional relational databases, a graph database is schema-less and can be flexibly extended without explicitly redefining the structure of the database. This enables customer profiles to be easily augmented with new data elements and relationships.

Detailed information about graph databases can be found in Wikipedia.

A profile comprises two elements: nodes, and relationships between nodes called "edges."

  • A node represents a single entity, such as a session, a customer identity, or a product. Nodes are generally nouns.
  • Edges between nodes indicate active relationships, such as "User A HAS_VIEWED Product X," or "User B BELONGS_TO Segment Y."

The image shown illustrates an abstraction of a profile structure in the graph, with circles representing nodes and lines representing edges. For simplicity, the edge relationships are not labeled in this image.

Profile Example

The following image is derived from actual profile data in the graph database. Both nodes and edges are labeled in this image.

How a Profile is stored

In the labeled image, the central Session node represents a user's session on the YaaS Storefront. Two VIEWED relationships associate the central Session node with the two products that the user viewed during the session. The text box overlaying the image shows details about a partially-obscured Category node associated with one of the Product nodes.

Write data into the customer profile graph

A dedicated enricher service writes particular data to the customer graph: One enricher persists a customer's identifying information, another persists a customer's orders, and so forth. Metadata for each dedicated enricher specifies a context schema defining the request that triggers the enricher, and nodes and relations schemas defining the elements that the enricher persists in the graph. For example, the following schemas are specified in the metadata for the Keyword Search enricher:

  • Schema context/commerce/KeywordSearch: Specifies that a KeywordSearch request triggers this service.
  • Schema nodes/commerce/KeywordSearch: Specifies that this service writes a KeywordSearch node to the graph.
  • Schema nodes/commerce/KeywordSearch/searchTerm: Specifies that this service writes a searchTerm attribute to the KeywordSearch node.
  • Schema relations/commerce/Session/commerce/KeywordSearch/commerce/PERFORMED: Specifies that this services writes a PERFORMED edge associating a Session node with a KeywordSearch node.

As a result, when a customer performs a keyword search for the term "cameras", a context/commerce/KeywordSearch request triggers the Keyword Search enricher to write these elements to the graph:

KeywordSearch graph elements


Data Input

Incoming data that contributes to a profile is called context. All incoming context is processed by context adapters: microservices that receive context, optionally adapt or transform it, and submit it for further processing by SAP Hybris Profile.

There are several methods through which you can submit context to context adapters. For detailed instructions about implementing these methods, see the Submit Data topic in the Development section.

Hybris Commerce Suite Extension

A Hybris Commerce Suite extension installed in an SAP Hybris Commerce Suite instance enables your storefront to submit a wide variety of events to SAP Hybris Profile, including order events, click events, technical data, and behavioral data. For more details, see the Hybris Commerce Suite Extension section of the Submit Data topic.

YaaS Storefront Extension

YaaS provides a storefront template that helps you set up and customize a fully-functional online storefront to submit user-identity and commerce data to the SAP Hybris Profile system. For more details, see the YaaS Storefront Extension section of the Submit Data topic.

Direct to Profile Services

Any source system can push data to SAP Hybris Profile using HTTP POST requests to SAP Hybris Profile service endpoints. Partners can create new endpoints to be integrated into their system and added to the YaaS Market. For more details, see the Direct to Profile Services section of the Submit Data topic.

Partner Service Extensions

As an SAP Hybris partner, develop customized context adapters to capture new data and customized enrichers to intelligently add new information to customer profiles. For guidance about developing customized services, please post a question on our Experts Forum.


Data Flow

This section introduces the internal processing of data in the SAP Hybris Profile system. For details, see the Process Data topic in the Development section.

SAP Hybris Profile applies a decentralized architecture for data processing. Independent microservices ingest, normalize, intelligently enrich, and store the data that enters the system. Each microservice targets a particular data type, such as particular order events. This decentralized architecture has these benefits:

  • You can extend the domains of data collection and processing through the addition of new microservices without requiring adjustment of existing system components.

  • Microservice independence improves the performance and resilience of the system under load and in response to temporary service failures.

Microservices encrypt each data element with an algorithm unique to that data type. This allows fine-grained control of data collection and usage. Data consent is applied to individual data types within a customer profile rather than globally to the profile as a whole. See the Manage Consent topic for details.


Data Output

There are three primary methods for reading data from the SAP Hybris Profile system.

  • Retrieve data directly from the graph with the Secure Graph service.
  • Send notifications in response to graph changes to any consuming application with the Catapult service.
  • View and navigate small sets of profile data stored in the graph with the Graph Explorer tool.

For detailed instructions about using these methods, see the Extract Data topic in the Development section.


Manage Consent

Customers might share sensitive personal information with a company through SAP Hybris Profile. Data privacy and responsible data management are essential to building trust between a company and its customers. Privacy encompasses not only data security and data encryption, but also a robust consent management system that allows customers to control the collection and the use of their personal data.

Personal data includes:

  • Technical browser attribute and device information
  • Products viewed in a web store
  • Conclusions based on interactions in a web store
  • Location-based data, such as data derived from the IP address of the user
  • Demographic conclusions, such as age, hobbies, and spending patterns

To address data privacy, SAP Hybris Profile allows customers to grant and revoke consents at any time. Revoking consent has these effects:

  • No more data of that type is collected about this customer. This restriction applies as soon as consent is revoked.
  • Existing data of that type, and all associated data, becomes inaccessible.

This image shows the results of a customer's revocation of consent for purchase data: Previously-collected information indicating that the customer's order HAS a payment and CONTAINS a product is inaccessible, and you can no longer collect such data. However, the product and payment data remains, disassociated from the customer's identity.

Consent revoked

To learn more about consent in SAP Hybris Profile, see the Consent Service documentation.

You can use the Consent Service API to:

  • Create or retrieve a consent reference for a given user and tenant
  • Execute a batch request that contains up to ten sub-requests
  • Retrieve a list of all consent classes
  • Create or update existing consent classes
  • Retrieve a single consent for a particular schema and user

SAP Hybris Profile provides a consent management template that a company can leverage to create a consent management user interface (UI). This template uses the Consent Service API to determine, grant, and revoke consents.

Consent UI


Development Steps

To develop your SAP Hybris Profile system, follow these steps:

  • Learn how to set up a YaaS project and SAP Hybris Profile.
  • Learn how to submit data to the system.
  • Learn how to extract data from the system.

Click the links in the image shown to navigate to the relevant topics for each step.

Getting Started with SAP Hybris ProfileHybris Commerce Suite ExtensionYaaS Storefront ExtensionDirect to Profile ServicesSecure Graph ServiceCatapult ServiceGraph Explorer Tool


Getting Started with SAP Hybris Profile

To install and configure SAP Hybris Profile through YaaS, you must:

  • Create a project to function as your company's workspace within YaaS.

  • Subscribe your project to these required SAP Hybris Profile packages:

    • Profile Core Services
    • Profile Services for Commerce

To set up your project and subscribe to the required packages, follow the instructions in the Builder documentation.


Submit Data

This section contains instructions for submitting data to the SAP Hybris Profile system using these methods:

Hybris Commerce Suite Extension

Purchase and install an SAP Hybris Commerce Suite instance and add the Hybris Commerce Suite extension to enable your storefront to submit a wide variety of events to SAP Hybris Profile. These events include order events, click events, technical data, and behavioral data. Learn about details of the events as well as how to use the extension on the SAP Hybris Help website.

YaaS Storefront Extension

Follow these instructions to set up and customize an online YaaS storefront to submit user identity and commerce data to the SAP Hybris Profile system, including:

  • user identity
  • login events
  • page views
  • keyword searches
  • category views
  • product views
  • shopping cart events

Set up a client for the YaaS storefront

  1. In the Builder, select the organization that you want to use, and either choose the appropriate project or create a new one.

  2. Next, set up two new clients in this organization: one for the administration of, and one for the operation of, the storefront. For the instructions on how to set up a client, see the Create a Service document. Each new client requires certain scopes, which define the actions and resources that are permitted for that client.

For security reasons, consider defining restricted roles for this project. You can learn how in the Account service documentation.

Subscribe to packages

Subscribe to packages in your project using these steps.

  1. On the Builder home page, select your project from Projects.
  2. From the Administration menu in the left-hand navigation, go to Subscriptions.
  3. Click +Subscription to go to the YaaS Market.
  4. Subscribe to these packages:
    • Cart
    • Checkout
    • Customer Accounts
    • Order Management
    • Product Content
    • Profile Core Services
    • Profile Services for Commerce
    • Site Management

In the SAP Hybris Profile system, you cannot collect data unless a user explicitly grants consent for that type of data. Data consent applies to one or more schemas that describe the type of data to collect. You can find more information about consent here.

After you set up a new project, also known as a tenant, use schemas to define the data types that your tenant can collect and persist. Here are two example schemas:

  • nodes/commerce/Product – A node schema that represents a product
  • relations/commerce/Cart/commerce/Product/commerce/CONTAINS – A relationship schema that indicates that a cart contains a product

Follow these steps to grant tenant-level consent for default schemas that represent the data types your tenant can collect and persist:

  1. Select your project from the Builder home page and open your administration client.
  2. In the Client Authorization section, click GENERATE ACCESS TOKEN.
  3. Select the hybris.profile_consent_manage scope and then click GENERATE to create a temporary bearer access token. Copy the value of this token.
  4. Access the Consent Service API Reference and copy the SERVICE URL value. Browse to the service URL and POST to the /{tenant}/consentReferences endpoint, using the name of your tenant and the copied token value.

Set up the storefront

Follow the instructions in the Set up a storefront topic in the Getting Started documentation. You can then add categories, products, and other elements to your new storefront.

Configure the storefront

Configure your storefront to send data to the SAP Hybris Profile system. Add the code snippet shown before the closing </body> tag of the storefront index.html file:

<script async defer src="js/vendor-static/piwik.js"></script>
<div ytracking></div>

You can now send events from your storefront to SAP Hybris Profile, and start building profiles!

Direct to Profile Services

SAP Hybris Profile provides these service endpoints that accept HTTP POST requests to persist data in the graph:

Sample use case: first steps

This section explains how you can check which data types SAP Hybris Profile registers, processes, and stores, and the prerequisites for the specific types of data you write in the system.

Get all schemas

To learn which data types you can write in SAP Hybris Profile after you subscribe to the relevant packages, get the list of all schemas defined in the metamodel database.

To see the list of all available schemas, make a GET request using a /schemas endpoint, as demonstrated in the API Reference section of the Enricher Authorization service documentation.

Find the relevant context adapter

When you find a schema that defines the type of data you are interested in, subscribe your project to the adapter that your schema writes to. To determine which adapter you need, check the details of a given schema by calling the /schemas/{schema} endpoint in the Enricher Authorization service. Among other details, a successful response includes the information about the adapter that writes the schema:

{
    "schema": "https://api.yaas.io/metamodel/v1/context/commerce/ProductView",
    "schemaTitle": "Product View",
    "schemaDescription": "Product viewed action",
    "consentClass": "ClickStream",
    "encryptionType": "user",
    "searchable": false,
    "lastUpdatedAt": "2015-01-02T14:32:12.321Z",
    "lastUpdatedByHybrisClient": "hybris.profile-piwik",
    "triggeredEnrichers": [
        {
            "id": "hybris.profile-yaas-mdata-enr",
            "name": "Yaas Master Data Enricher",
            "channelType": "PSH"
        },
        {
            "id": "hybris.profile-enricher-poc",
            "name": "Enricher PoC",
            "channelType": "PSH"
        }
    ],
    "writtenBy": [
        {
            "id": "hybris.profile-piwik",
            "name": "Piwik service"
        }
    ]
}

As shown in this example, the details of a given schema include the ID and name of the context adapter to which that schema writes.

Submit data to a context adapter

To learn how to submit data to a given adapter, navigate to the API Docs section, where you can find documentation regarding all available context adapters. In the left-hand search bar, you can enter the name of the required context adapter or search for the name of the package that contains the context adapter you are interested in.

Context adapters are available in two packages: Profile Core Services and Profile Services for Commerce.


Process Data

This section explores the flow of data that enters the SAP Hybris Profile system.

Profile Data Flow

  1. An incoming request targets context adapters. Context adapters optionally transform context —— for instance, by normalizing address formats —— before passing it to the Context service.

    You can call the Context service both by context adapters, and directly.
  2. An event is dispatched to enrichers. Note that each request, such as a product view event, contains a schema that is associated with a set of enrichers.
    A single schema can trigger multiple enrichers.

  3. The enricher optionally fetches additional context data. For example, it can interpret purchasing data and contemporaneous weather station data to yield new data that indicates the customer is a rainy-day shopper. The enricher can use additional data from the customer profile graph during this enrichment process.

  4. The enricher calls the Secure Graph service to persist the enriched data in the customer profile graph as nodes and edges, defined by the enricher's schemas. The Secure Graph service writes the information about the changes in the customer profile graph to the Context service, which, in turn, can trigger other enrichers.

  5. The updated customer profile graph optionally triggers a real-time notification through the Catapult service. This notifies consuming applications about relevant changes in a customer profile such as abandoned carts, negative sentiments, or decreasing purchase activity. A consuming application, such as a marketing application, can react to such notifications in real time, for example by sending a message to a customer's mobile device.


Extract Data

This section describes methods for reading data from the SAP Hybris Profile system.

  • The Secure Graph service provides GET methods to retrieve data from the graph. In particular, this service's neighbours endpoint retrieves information about a particular node in the graph, along with "neighbor" nodes that are directly related to the requested node. For example, this endpoint can retrieve information about a particular shopping cart node, and about the neighboring product nodes associated with that shopping cart node.

  • The Catapult service allows you to send notifications through YaaS to any consuming application, including notifications based on changes in the graph. For example, a customized service combines information about a new shirt purchase with conclusions about customer intent, and then informs the marketing system through the Catapult service. As a result, the integrated system can email a coupon for discounts on business travel attire with relevant product recommendations to the customer.

  • The Graph Explorer is a debugging tool that is automatically enabled in your Builder project when you subscribe to the SAP Hybris Profile Core Services package. The tool enables viewing and navigation of small sets of profile data stored in the graph, and is useful for verifying that profile data is stored with the expected nodes and edges. Each Graph Explorer query retrieves a specified target node, its immediate neighbors, and edges connecting those nodes. You can navigate through the graph by specifying a new target node, either through a new query or by clicking a displayed node.

    The image shows graph data that the Graph Explorer tool retrieved and displayed:
    Graph Explorer display example

For more details about the Graph Explorer and how to use it, see the dedicated documentation.


Extract Aggregate Data

The SAP Hybris Profile system provides a Real-time Reporting service that enables analysis of data aggregated from multiple sources over time. This documentation provides a comprehensive description of the Real-time Reporting service's functions.

Data enters the Real-time Reporting service through two channels: The SAP Hybris Commerce Suite extension submits commerce events, and the Profile Tag submits clickstream events. The Edge service ingests the events submitted through these channels and passes them to the appropriate processors. These processors then submit transformed data to the Real-time Reporting service.

Real-time Reporting data ingestion


Track data in the Trace Explorer

Tracing module

By monitoring events in SAP Hybris Profile, you can gather the details about the exact time of calls between services, and the duration of specific operations. Monitor events using a tracing tool based on the Zipkin tracking system, and defined in YaaS as a Trace Explorer Builder module.

SAP Hybris Profile collects timing data from the core services and enrichers to help you identify any latency problems. For example, when a service sends a request to an enricher, it passes the information about the time of the call to the system, and you can retrieve the information later. The system also gathers information about the time the enricher receives the request, as well as when that enricher returns the processed data.

Available trace data

This data is available in the Trace Explorer:

  • The time the source service sends an outbound request
  • The time the target service receives a request
  • The time the target service responds to a request
  • The time the source service receives an inbound response

By analyzing this data, you can measure how much time a request needs to reach a given service, how long it takes that service to process the request, and how much time passes until the source service receives a response.

Track events

Each event has a unique contextTraceId attribute that you can use to track the route of the event in SAP Hybris Profile. For more details about the contextTraceId attribute, see the Context events section.

To activate event tracking across SAP Hybris Profile, include a X-B3-Sampled header with a value of 1 in your request to the Context service. If you pass this header with a value of 0, or do not include this header in your request at all, tracking is not activated.

Monitor event flow in the Trace Explorer

The Trace Explorer Builder module is part of the Profile Core Services package. Subscribe to that package to get access to the Trace Explorer.

To fetch the tracked data, follow these steps:

  1. Go to the Builder.
  2. In the left navigation menu, click Hybris Profile Developer Tools.
  3. Select the Trace Explorer module.
  4. To read the timing data about the events processed by a given enricher, go to the ENRICHER ID tab and complete the dedicated field with the ID of that enricher. Alternatively, to see which services processed that event, go to the CONTEXT TRACE ID tab and enter the id from the Context service response in the dedicated field.
  5. Click SEARCH in either of the tabs to display the visualized traces. The traces consist of the spans that symbolize the services involved in the flow, and their execution time.

Debug enrichers

Using Trace Explorer, you can monitor whether enrichers receive and process events successfully. To track the event flow, pass a X-B3-Sampled header with a value of 1 in your request to the Context service, as shown in the example. For more details, see the Track events section.

curl -X POST -H "Authorization: Bearer 022-f9d7fabb-06bb-4b42-b0c2-c7716a7ff89e" -H "consent-reference: 56bd66f8-22f3-447e-8636-51ef6c9c71c1" -H "X-B3-Sampled: 1" -H "operation: STORE" -H "schema: context/commerce/ProductView" -H "Content-Type: application/json" -d '{
    "customerId": 1122322241,
    "productId" : 11232222315,
    "action"    : "view",
    "tenant"    : "mytenant"
}' "https://api.yaas.io/hybris/profile-context/v1/mytenant/data"

The response includes the id attribute that becomes a contextTraceId of a given event flow:

{
  "id": "523dd1d0-de4d-11e6-99a8-d9bb373dc57d",
  "link": "https://api.yaas.io/hybris/profile-context/v1/mytenant/data/523dd1d0-de4d-11e6-99a8-d9bb373dc57d",
  "consentRefId": "c14cc93c-9b12-46a2-8c47-9bc504412be3"
}

To see which services processed that event, copy the id attribute, and go to the Trace Explorer Builder module. Open the CONTEXT TRACE ID tab and enter the copied id in the dedicated field, then click SEARCH

Alternatively, search the details of enricher event processing by enricherId, which equals the ID of a given Builder module. For more details, see the Create Builder module section.

Enable tracing in your storefront using the dedicated script

To enable tracing in your storefront, follow these steps:

  1. Insert the following script into the website when building your storefront.
        window.Y_TRACING = window.Y_TRACING || function () {
                (window.Y_TRACING.q = window.Y_TRACING.q || []).push(arguments);
        };
        
        var s = document.createElement('script');
        s.type = 'text/javascript';
        s.async = true;
        s.src = 'https://s3.amazonaws.com/blobs-yaas-storks/tracing-for-storefronts/tracing.min.js';
        var x = document.getElementsByTagName('script')[0];
        x.parentNode.insertBefore(s, x);
        
        window.Y_TRACING(
        {
            tenant: 'yourtenant',
            builderUrl: 'https://builder.yaas.io/',
            basePiwikUrl: 'https://api.yaas.io/hybris/profile-edge/v1/'
        });
    
    Provide the following parameters in the script:
    • tenant: Your tenant name
    • builderUrl: The URL of the Builder
    • basePiwikUrl: The URL of the Edge service
  2. Add the profileTracingDebug parameter to the storefront URL and set its value to true. Your storefront URL should look as follows: http://example.com?profileTracingDebug=true.
  3. The script inserts a X-B3-Sampled header with a value of 1 into the payload of the events that customer activity in the storefront generates. The storefront then sends the events to the Edge service.
  4. The Edge service response contains the contextTraceId that you can use in the Trace Explorer to read the traces of a given event. Additionally, a link generated on the basis of that contextTraceId appears at the top of the screen.
  5. Click the link to open the Trace Explorer, where you can view all traces for a specified contextTraceId.

Enable tracing in your storefront using the Profile Tag

You can also enable tracing in your storefront using the Profile Tag in the debug mode. To learn what the Profile Tag is, and how it works, see the Profile Tag documentation.

To trace customer activity in your storefront using the Profile Tag, follow these steps:

  1. Activate the Profile Tag debug mode by adding the profileTagDebug parameter to your storefront URL and setting the parameter to true. With this debug flag, your storefront URL should look as follows: http://example.com?profileTagDebug=true.
  2. Open your developer tool to view the details available only in debug mode, such as tenant name and contextTraceId, associated with events that customer activity generates.
  3. Copy the contextTraceId from your developer tool.
  4. Open the Trace Explorer in the Builder.
  5. Paste the copied contextTraceId into the dedicated field in the CONTEXT TRACE ID tab.
  6. Click SEARCH to see the traces for a specified event.

Trace logs

To read the data about the events that a given enricher processes, go to the Trace Explorer Builder module and open the ENRICHER ID tab. In the dedicated field, enter the ID of the Builder module that the enricher is registered as, and click SEARCH.

The traces that the Trace Explorer displays consist of spans that indicate how much time each service needed to process a given message.

One contextTraceId identifies a full, single event flow -- the route from the Context service through an enricher and the Secure Graph, back to the Context service. An event from the Context service triggers an enricher. The enricher introduces changes to the Profile graph, which results in a new event that triggers another enricher. This cycle is identified by a single contextTraceId. When changes that the enricher makes in the Secure Graph result in a new event that triggers another enricher, a new event flow with a new contextTraceId begins. This is when a Context Transition takes place.

By displaying contextTraceId attributes in the Context Transition UI element, Trace Explorer shows how many event flows a given enricher was involved in.

Apart from the contextTraceId values, the Trace Explorer also displays schemas associated with each contextTraceId that stands for a given event flow. The schemas define events created by one enricher and triggering another enricher, and indicate where a context transition takes place.

Error scenario

The Trace Explorer helps you diagnose any event processing problems. If your enricher fails to process an event, you will see an error message in the logs. An error message indicates why the operation was not successful so that you can fix the problem.

For example, when the message indicates that you do not have a consent for a given schema, go to the Consent service to resolve the issue.


Customize code with the Configuration Explorer

The Configuration Explorer is a visual interface for the Configuration service, which is a part of the Persistence package. Using the Configuration Explorer, you can change the behavior of your extensions more easily by adjusting the properties of the code, instead of modifying the code itself. Using the Configuration Explorer means less code, fewer bugs, and more control.

Because properties are scoped to the current project to which an enricher is subscribed, only members of that project can customize the enricher's behavior. Another benefit is that you can reuse some common parts of the code, routines, or even whole services, and run them parametrized. Create your own set of variables or configure the pre-defined variables to include them in your source code, and use them with other extensions, such as the Builder modules.

The Configuration Explorer allows you to define tenant-level configurations only.
The Configuration Explorer is not intended for storing passwords or sensitive data.
To find information about consuming defined properties, refer to the Configuration service documentation.

Access the Configuration Explorer

The Configuration Explorer is a part of the SAP Hybris Profile Core Services package. When you subscribe to the SAP Hybris Profile Core Services package, the system automatically enables the Configuration Explorer for Builder projects of one tenant. Follow the instructions in the Builder documentation to subscribe to this package.

Follow these steps to access the Configuration Explorer.

  1. Open the Builder.
  2. Click your project.
  3. In the left navigation menu, click Hybris Profile Developer Tools.
  4. In the left navigation menu, click Configuration Explorer.

Use the Configuration Explorer

Use the Configuration Explorer to define, edit, or remove variables for use in other extensions.

To define a new variable, follow these steps:

  1. In the Configuration Explorer, click + variable. A pop-up window titled Add a new variable appears.
  2. Enter the name of your variable in the Variable Name field.
    The name of a property must must start with a letter or a number, be between one and 36 characters long, and can contain uppercase or lowercase letters, numbers, and the following characters: -, _, ., |, @.
  3. Provide the value of your variable in the field Value.
  4. Click Add to save your changes and add the newly-defined variable. The window closes automatically and a list of your variables appears.

Edit or remove variables

You can edit or remove entries at any time. To do so, use the pencil and bin icons on the right. Click the pencil icon to edit the details of your variable, or the bin icon to remove the whole entry.


Manage identities

Identity resolution and identity management are key enablers for contextual marketing and commerce by connecting multiple sources of identity and customer information to support robust targeting, personalization, and addressability across touchpoints and devices. The SAP Hybris Identity service clusters all of a user's identities around a single profile. It provides service endpoints to create, read, alter, and delete identities, profiles, and their relations.

Use cases

The following examples explain the benefits of proper identity management.

Scenario 1: Customer uses multiple devices

Assume an anonymous customer interacts with a brand without signing in, first using a mobile device and later a PC. At this point, in the beginning, the system can only create two different profiles and two different identities.

Anonymous customer with two profiles

At a later point, that customer signs in for the first time on either of the two devices. One of the profiles receives an additional identity. Then that customer uses the same login on the other device, too. Now SAP Hybris Profile knows that these two profiles are the same person.

Identified customer with two profiles

This puts SAP Hybris Profile in a position to merge these two existing profiles into one. Suppose that SAP Hybris Profile chooses the light blue profile to live on; the dark blue profile gets abandoned. The customer continues to use the PC. The interactions with the brand send events that come with consent reference B. The Identity service makes sure that these events find their way to the profile with consent reference A. Identified customer with one merged profile

Whenever customers make changes to their consents, this affects the consent settings on all devices. Consider a customer using a mobile device to revoke consent for age estimation. Later, the same person opens the consent management page on a PC and sees that consent revoked. This is omni-channel consistency!

Consistent consent management

Scenario 3: Consistency at consumption

If a consuming application uses SAP Hybris Profile to obtain information on a specific user, the SAP Hybris Identity service makes sure that it does not matter how the consuming application identifies a consumer. It always returns the same profile.

Consistent profile consumption

Profile Merge

As soon as two profiles share sufficiently significant identities, for example a registration email or StrongId, the Merge service combines the two profiles into one.

For example, a customer who already has an account surfs a storefront anonymously, without signing in. Until the customer signs in, SAP Hybris Profile keeps two user profiles:

  • one connected with the customer's account
  • one for the customer's current anonymous session

The moment the customer signs in to the current session, the Merge service starts. The service makes sure that for the rest of the current session, the Profile system enriches the customer's known profile. The Merge service transfers every observation or insight from the anonymous session's profile into the existing profile. When the merge is complete, the service deletes the newer, anonymous session profile.

The service combines the profiles in these steps:

  1. The service aligns both profiles' consent settings. Only those consents that the consumer granted in both profiles' settings remain granted. In other words: as soon as a user revokes a consent of any consent settings of the two profiles, or it doesn't even exist in one of them, this consent will not be granted in the consent settings of the merged profile
  2. The service redirects the identities, assigning each to a single prevailing profile.
  3. The service merges the profile documents, bundling all observations, insights, and so forth into one single profile. In cases where the original profiles have contradicting information, such as different affinities to the same product, the system uses the data in the chronologically older profile.

Technically, the Merge service is an enricher. The creation of IDENTIFIES edges between identity and profile nodes triggers the Merge service. If an identity node involved in the creation of an IDENTIFIES edge has one of the following combinations of values, the Merge service enricher combines the profiles.

  • identityType=sid and identityOrigin=web
  • identityType=email and identityOrigin=<arbitrary>

Profile document management for profile merge

When merging two profiles, this service carries over all of the necessary information, from the most recently-created profile to the chronologically older profile that the Profile system maintains. The profile document contains the details for both of the profile IDs supplied to the service. Finally, the service deletes the newer profile.

Identity management for profile merge

When merging, the Merge service sends the two profile IDs to the Identity Service, which keeps the older profile ID and deletes the newer ID. The steps in this process include:

  1. The service gets all the identities associated with the newer profile ID.
  2. For all of the identities from the newer profile, the service adds a relationship from these identities to the older profile.
  3. The service deletes the newer profile, which also deletes the relations between the profile and the identities.

the Merge service combines profiles that share an identity. This section describes how the Merge service handles consent management for the merged profile.

After the Merge service combines profiles, SAP Hybris Profile maintains only the merged profile document, regardless of which profile's consent references the Profile service uses to retrieve it. The consent merge functionality uses the consent settings of the two profiles to decide on the consent settings of the merged profile. The service picks up all the consent schemas that are either absent in one or both of the consent references, or have different values. It sets these schemas to false and makes no changes to the values granted in both references.

Example

This is an example of a consent table before the merge:

Consent classProfile AProfile X
Product affinity
Category affinity
Age
Cart
.........

This is the same consent table after the merge:

Consent classProfile AProfile X
Product affinity
Category affinity
Age
Cart
.........


Manage Metadata

The metamodel is a graph database within the SAP Hybris Profile system that persists metadata that describes service functions and relationships. See the Enricher Authorization (Metadata) service for details about how to register, view, and manage service metadata in the metamodel.

Context adapter metadata

Each context adapter registers writesTo metadata in the metamodel that describes its generated context events. The following metamodel registration entry specifies that the Clickstream Statistics Context Adapter generates context/commerce/ClickstreamStatistics events that are encrypted at the tenant level:

{
  "name": "Clickstream Statistics Context Adapter",
  "writesTo": [
    {
      "schema": "context/commerce/ClickstreamStatistics",
      "schemaTitle": "ClickstreamStatistics",
      "schemaDescription": "Clickstream action",
      "consentClass": "ClickStatistics",
      "encryptionType": "tenant"
    }
}

Enricher metadata

Each enricher registers two types of schemas in the metamodel:

  • triggeredBy: The schemas defining the context events that trigger the enricher
  • writesTo: The schemas defining the data structures that each enricher writes to the graph

This example illustrates a registration entry in the metamodel for an enricher that is triggered by Clickstream Statistics Context Adapter context events, and writes page click (PageClicks) and page bounce (PageBounces) data to the graph:

{
  "name": "Click Speed Enricher",
  "triggeredBy": [
    "context/commerce/ClickstreamStatistics"
  ],
  "writesTo": [
    {
      "schema": "nodes/commerce/PageClicks",
      "schemaTitle": "Total Page Clicks",
      "schemaDescription": "Total number of page clicks",
      "consentClass": "ClickStatistics",
      "encryptionType": "tenant"
    },  
    {
      "schema": "relations/commerce/Session/commerce/PageClicks/commerce/HAS",
      "schemaTitle": "Has Total Page Clicks",
      "schemaDescription": "Session has clicked this number of times",
      "consentClass": "ClickStatistics",
      "encryptionType": "user"
    },

    {
      "schema": "nodes/commerce/PageBounces",
      "schemaTitle": "Total Page Bounces",
      "schemaDescription": "Total number of page bounces",
      "consentClass": "ClickStatistics",
      "encryptionType": "tenant"
    },    
    {
      "schema": "relations/commerce/Session/commerce/PageBounces/commerce/HAS",
      "schemaTitle": "Has Total Page Bounces",
      "schemaDescription": "Session has total number of page bounces",
      "consentClass": "ClickStatistics",
      "encryptionType": "user"
    }
    ...
}

Other metadata

The metamodel also includes more global information, including:

  • The available tenants and enricher services
  • The enricher services to which each tenant is subscribed
  • Relationships among data elements (nodes and edges)
  • Properties of nodes and edges

Modify the metamodel event flow

Because the metamodel stores data in a graph form that you can arbitrarily alter and extend, the relationships among data in the metamodel are not fixed, and you can significantly alter these relationships by changing the metamodel data structure.

The modification of the data flow can be different for each tenant.

Subscribing to new enrichers and context adapters, as well as unsubscribing from pre-existing enrichers and context adapters, changes data-flow pathways in the system. Adding or removing enrichers in the metamodel might cause the other enrichers that exist within a project to either initiate or cease communication with one another. As a result, the data flow that an event triggers can follow a new route.

This diagram illustrates the data flow definition in the metamodel: Enricher 1 writes to Schema 1, which in turn triggers Enricher 2 to write to Schema 2.

graph LR A[Enricher 1] --WRITES_TO--> B((Schema 1)) B --TRIGGERS--> C[Enricher 2] C --WRITES_TO--> E((Schema 2))

Consider a scenario in which you add a new enricher to the metamodel. The new enricher writes a type of data similar to that of Enricher 2 in the diagram. If the client prefers the newly-added enricher because it is more efficient than Enricher 2, you can direct the data towards, and process it through, the new enricher instead of the original.

In this scenario, Enricher 2.1 is added to the metamodel so that it replaces Enricher 2's functionality. Note the change of the data flow.

graph LR A[Enricher 1] --WRITES_TO--> B((Schema 1)) B -.-> C[Enricher 2] B ==TRIGGERS==> D[Enricher 2.1] C -.-> E((Schema 2)) D ==WRITES_TO==> E((Schema 2))

Metamodel viewer

Metamodel viewer is an interactive tool that represents, or shows, the relationships between schemas and enrichers or context adapters in the metamodel in a clear, visual way. Use the viewer to see which events trigger particular enrichers and context adapters, and which data elements those enrichers and context adapters affect in the graph. Corresponding schemas represent these events and data elements.

This graphic shows a metamodel viewer for a Product Details enricher.

A metamodel viewer is available for all enrichers and context adapters. You can find it in the Metamodel subsection of each document that describes an enricher or context adapter.


Schedule Events

The purpose of event scheduling

Event scheduling allows you to plan the delivery of specific events in advance. Using this functionality, you can send events to SAP Hybris Profile after a predefined amount of time, rather than immediately.

You can integrate event scheduling with the Secure Graph service to introduce scheduled modifications to the graph. For example, you can determine that the affinity of a given relation, such as a relation between Product and Session, should decrease by a preferred value after a specified amount of time. To make such affinity modifications, you must subscribe to the specific enricher that reacts to a given scheduled event.

You can enable event scheduling when creating or updating graph nodes, relations, and attributes. To learn how to set the event delivery time when calling the Secure Graph service, see the Event scheduling tutorial.

Sample scenario

To make the customer affinity to a product decrease over time, your enricher must pass the hybris-schedule-event-at header with the specified event delivery time, and, optionally, a hybris-schedule-event-parameter header containing custom string data, when calling the Secure Graph service. After a given amount of time, an enricher that reacts to the scheduled event receives a message informing it that the customer affinity to a product needs to be modified. Triggered by such an event, the enricher modifies the customer affinity, as specified in the event payload.

If you update a node, a relation, or a property multiple times with different scheduleAt and scheduleParameter values, thereby changing the details regarding the scheduled event execution, you receive a single event associated with the scheduleAt and scheduleParameter values included in your most recent update. The final update with the event scheduling settings overwrites all the previously-defined values.

Data flow

The following diagram shows how the data flows in SAP Hybris Profile if you define the event delivery time when calling the Secure Graph service. The demonstrated example centers on the node creation operation.

Scheduled Event Flow

  1. Your enricher sends a node creation request to the Secure Graph service. To enable event scheduling, your enricher must include the specified headers in the request sent to the Secure Graph service. For more details about the specified headers, see the Event scheduling section.

  2. The Secure Graph service sends a store event to the Context service. This notification event contains data that determines when the system sends the scheduled event. For an example of such a notification event, see the Sample store event topic.

  3. The Context service registers the time to trigger the delivery of the scheduled event. After the specified amount of time, the Context service is prompted to send the scheduled event.

  4. The Context service sends a scheduled event. The event can trigger an enricher that you are subscribed to. As a result, the enricher introduces the desired changes to the Profile graph. For an example of the scheduled event, see the Sample scheduled event topic.



Introduction to the enricher and context adapter integration

This section explains how to integrate enrichers and context adapters with SAP Hybris Profile.

This section covers these topics:

  • Enricher integration

    • Create a Builder module in YaaS
    • Register your enricher in the metamodel
      • Create a topic (only relevant for enrichers)
      • Define triggeredBy schemas
      • Define writesTo schemas
    • Integrate an enricher with the PubSub and Secure Graph services
      • Get messages from PubSub
      • Store data in the Secure Graph
  • Context adapter integration

    • Create a YaaS service in the Builder
    • Register your context adapter in the metamodel
      • Define writesTo schemas
    • Store events in the Context Service


Create a Builder module

Create a Builder module for your enricher

To create the proper environment for the registration of your enricher and its integration with SAP Hybris Profile, it is recommended that you create a Builder module in YaaS.

Unlike services, you do not need to directly access enrichers via an API to integrate them with SAP Hybris Profile. Therefore, if you want to register your enricher, define it as a Builder module, rather than as a service.

  1. Go to the Builder and select an organization.

  2. Navigate to Projects > {Your Project} > Builder Modules, and click + NEW BUILDER MODULE.

    You require a project to create a new Builder module. To learn how to create a new project, see the Create Projects section.
  3. Select a package, or packages, according to your needs. The Profile Core package is required for your enricher to function properly. For details about how to subscribe to packages, see the Submit Data section.

  4. Select the required scopes, then click Next. To use your enricher efficiently, you need these scopes:

    • hybris.profile_graph_view - required if your enricher reads data from the graph
    • hybris.profile_graph_manage - required if your enricher introduces changes to the graph
    • hybris.profile_context_view - required: allows your enricher to read events
  5. Complete the required fields in the Register Builder Module section.

    The identifier of the Builder module becomes your enricherId in the metamodel. The identifier must be unique within your organization.
  6. Click Save to register your Builder module in YaaS.


Enricher registration

To convert your Builder module into an enricher, register it in the SAP Hybris Profile metamodel. Before you register an enricher, you must define the schemas that trigger your enricher, as well as the schemas that represent the data structures it affects in SAP Hybris Profile.

Define triggeredBy and writesTo schemas

If the enricher that you create reacts to unique events, or affects unique data types in the graph, you might need to define new triggeredBy and writesTo schemas. Otherwise, browse a list of available schemas to locate the schemas that you require.

Browse available schemas

To check if the schemas that you require are already defined in the system, browse the list of all available schemas. Make a GET request using a /schemas endpoint, as demonstrated in the API Reference section of the Enricher Authorization service documentation.

The response returns all schemas registered in the metamodel. The example displays only a subset of the returned schema list:


[
    {
        "schema": "<a href="https://api.yaas.io/metamodel/v1/context/commerce/ProductView">https://api.yaas.io/metamodel/v1/context/commerce/ProductView</a>",
        "searchable": false,
        "encryptionType": "user"
    },
    {
        "schema": "<a href="https://api.yaas.io/metamodel/v1/context/commerce/AbandonAlertEvent">https://api.yaas.io/metamodel/v1/context/commerce/AbandonAlertEvent</a>",
        "schemaTitle": "AbandonAlertEvent",
        "schemaDescription": "Abandon Alert Event",
        "consentClass": "CartEvents",
        "searchable": false,
        "encryptionType": "tenant"
    },
    {
        "schema": "<a href="https://api.yaas.io/metamodel/v1/context/commerce/AddedToCart">https://api.yaas.io/metamodel/v1/context/commerce/AddedToCart</a>",
        "schemaTitle": "AddedToCartEvent",
        "schemaDescription": "Customer added a product to shopping cart",
        "consentClass": "CartEvents",
        "searchable": false,
        "encryptionType": "user"
    },
    {
        "schema": "<a href="https://api.yaas.io/metamodel/v1/context/commerce/CategoryView">https://api.yaas.io/metamodel/v1/context/commerce/CategoryView</a>",
        "schemaTitle": "CategoryView",
        "schemaDescription": "CategoryView action",
        "consentClass": "CategoryViews",
        "searchable": false,
        "encryptionType": "user"
    }
]
Only nodes and relations schemas can be used as writesTo schemas.

Define new schemas

If you are unable to locate the schemas that you require among the available schemas, you can define your own triggeredBy and writesTo schemas. When defining the properties of your schema, make sure to retain the standard schema format.

The properties that you need to determine when creating a new schema:

  • schemaTitle - the name of your schema
  • schemaDescription - a brief description of the scope of your schema
  • consentClass - the consent class to which your schema belongs
  • searchable - "true" or "false"; determines whether the schema is searchable
  • encryptionType - the type of encryption used to encrypt the data (tenant or user)

For details about how to register new schemas, see the Enricher Authorization service documentation.

Trigger by context events

Both context adapters and graph changes create context events that trigger enrichers.

Your enricher's 'triggeredBy' schemas specify which context events your enricher reacts to.

Note that graph changes executed by one enricher can trigger responses by other enrichers. For more details about the data flow among multiple enrichers, see the Manage Metadata section.

Currently, you can have your enricher react to the addition or deletion of the nodes and relations.
The Secure Graph writes to the Context service an event message that will trigger changes to the graph. Depending on the type of the event and the changes that it triggers, the message that the Secure Graph records in the Context service is written either as a nodes schema or as a relations schema.

Create a topic

Enrichers read messages from PubSub topics. Each enricher has its own topic. The topic name for your enricher is "profile.profile-dispatcher.{hybris-client}", where "hybris-client" parameter is your hybris client name from the Builder.

A topic for your enricher is automatically created upon the enricher registration. See the PubSub documentation for more details.


Enricher integration with PubSub

Get messages from PubSub

When an event occurs, the system sends a message to the PubSub service. The SAP Hybris Profile system creates a separate messaging channel, called a topic, for each enricher in the PubSub service. The topic owner is "profile.profile-dispatcher". Only one enricher is permitted to read messages from a given topic. For example, if you register an enricher with the ID "myorg.myenricher" in the metamodel, you can read its messages using the https://api.yaas.io/hybris/pubsub/v1/topics/profile.profile-dispatcher/myorg.myenricher/read endpoint. See the PubSub API Reference for more details.

By subscribing your tenant to the package that contains a given enricher, you implicitly allow that enricher to read, from its topic, the messages that belong to that tenant. An enricher reads only the events that are associated with the tenants subscribed to all of these packages:

  • any packages containing this enricher
  • the Events package
  • the Profile Core package

When you call the PubSub service, you must provide your enricher's credentials: Client ID and Client Secret. To retrieve those credentials, follow these steps.

  1. Go to the Builder.
  2. Select your organization.
  3. Navigate to Projects > {Your Project} > Builder Modules.
  4. Select your enricher and go to the Client authorization section.
  5. Click Unlock and copy your enricher credentials.


Enricher integration with the Secure Graph

Store data in the Secure Graph

Enrichers have full access to the Secure Graph API. Through calls to this API, your enricher can introduce changes to the graph, for example, by creating new nodes or relations. As a creator of an enricher, you must determine the ID of such new nodes and relations.

Node and relation ID

Use the following information when determining your node or relation ID:

  • The node and relation ID must be unique for each schema of a given type within a single tenant.
  • The ID of a node or relation cannot contain sensitive data, such as an email address or a telephone number. Such IDs cannot be safely encrypted because they are used in the REST links, which are stored in the search indexes.
  • When defining your node or relation ID, use natural keys. See the Wikipedia article for more details.
  • The ID of a node or relation is an internal property and, as such, is not defined in the metamodel.
  • An example of a session node with a sample ID is: mycomicsshop/nodes/commerce/Session/1b9d-8533d9a6e8ec

For details regarding other node and relation properties, see the Secure Graph service documentation.


Create a service

Create a service for your context adapter

To create the proper environment for the registration of your context adapter and its integration with SAP Hybris Profile, you must create a new service in YaaS.

Unlike enrichers, context adapters can be accessed directly through an API. Therefore, when registering your context adapter, define it as a service.

  1. Go to the Builder and select an organization.

  2. Navigate to Projects > {Your Project} > Services, and click + SERVICE.

    You need a project to create a new service. To learn how to create a new project, see the Create Projects section.
  3. Complete the required fields in the Register New Service section.

    The identifier must be unique within your organization.
  4. Click Save to register your service in YaaS.


Context adapter registration

Define writesTo schemas

Before you register your context adapter, you must specify the schema(s) identifying the type of event(s) that the context adapter passes into the SAP Hybris Profile system. For example, the schema context/commerce/ClickstreamStatistics indicates that the context adapter generates a clickstream statistics event.

Browse available schemas

To check whether the schemas that you require are already defined in the system, browse the list of all available schemas. To learn how to retrieve the list of schemas, see the Browse available schemas topic in the Enricher Registration section.

Only nodes and relations schemas can be used as writesTo schemas.

Define new schemas

If, among the available schemas, you are unable to locate the schemas that you require, you can define your own writesTo schemas. For details about registering new schemas, see the Define new schemas" topic in the Enricher Registration section.

Store events in the Context service

Contexts adapters receive events and adapt the data for entry into the graph. However, context adapters cannot directly call the Secure Graph service to persist data in the graph. Instead, context adapters pass the events to the Context service. The service then dispatches the events to enrichers, which persist the data in the graph.


Profile Tag

Tracking consumers on web pages requires capturing data while consumers browse the site. This is usually accomplished with a tracking pixel, or a tag: code inserted into a web page that sends data to the server. In the past, tracking pixels were transparent GIF images. Now, they are being replaced by more sophisticated tags based on JavaScript.

It can be cumbersome to manually create and maintain such tags throughout a website. SAP Hybris Profile Tag simplifies tag management and data capture. Via the easy-to-use Builder module, you configure the way data gets sent to SAP Hybris Profile. You can also test the configuration interactively in the live mode. SAP Hybris Profile Tag offers a flexible way to adapt to the structure of your online presence, and allows you to define the so-called events that you create by sending the information you wish to store in SAP Hybris Profile.

Profile Tag components

SAP Hybris Profile Tag consists of the following components:

  1. A Builder module - the graphical user interface to configure the tag for your website
  2. A JavaScript library to include in your website's code
    • enables the live-tagging during the design-time, and page configuration
    • captures elements of the page and sends their data to SAP Hybris Profile during the run-time

For more details about the Profile Tag components, see the Elements of Profile Tag section.

Purpose

The configuration is the core of the Profile Tag. The configuration defines which tracking events to send and how to compose the payload. With each page view, the Profile Tag reads the current configuration of a specified site, creates tracking events according to the configuration, and sends these events to SAP Hybris Profile.

This section explains how to set up the Profile Tag for a site and how to define or edit the configuration.

Prerequisites for Profile Tag

The Profile Tag is part of the SAP Hybris Profile Services for Core package. Subscribe to the required packages in your project by following these steps:

  1. Select your project from the Projects section in the Builder.
  2. In the left hand side navigation menu, click Administration, and then Subscriptions.
  3. Click + SUBSCRIPTION. The YaaS Market page opens.
  4. Subscribe to these packages:
  5. SAP Hybris Profile Core Services
  6. SAP Hybris Profile Services for Commerce

For more information, see the Builder documentation.

Elements of Profile Tag

Site

A site is a set of web pages, such as a web shop or a website, from which you can collect the data about customer interactions to build up customer profiles. A site can be a website, or any other online presence, which is capable of executing JavaScript. In the most common use cases, the Profile Tag is used by an online shop, such as www.someshop.com. If the internal structure of the pages or privacy regulations between www.someshop.com/us and www.someshop.com/de differ greatly, set up two sites, one for the US version and one for the DE version.

Pages & Page Types

A site usually has many pages. A shop with 100 products most likely has a product detail page for each of these 100 products. Besides that, the site can have an "about" or "imprint" page, a start page, a cart page, perhaps a range of landing pages for SEM or other campaigns, category pages, keyword search result pages, and so on. The content of 100 pages might differ, each showing a different product, but their internal HTML structure does not differ. All pages have similarly composed titles, header elements, add-to-cart-buttons, and so on. A tenant that wishes to track user behavior on product detail pages, most likely wants to track it on all 100 pages.

That is why in the Profile Tag, you can configure Page Types, as well as define how the Profile Tag is supposed to compose and send tracking events.

Configuration

The goal of the Profile Tag is to create and send service calls to SAP Hybris Profile. In order to send the correct events with the correct payload, each tenant has to set up a configuration which tells the Profile Tag how to translate the elements of the tenant's site into the relevant service call payloads. A tenant makes the configurations in the Builder, and then store them in, and retrieve them from, a remote storage. A tenant creates separate configurations for different page types within his site.

Tag

If a page is supposed to send events to SAP Hybris Profile, the page needs to have the Profile Tag JavaScript introduced. This script fetches the configuration for this site and applies the appropriate configuration to the current page to generate and send off the tracking events to Profile.

Builder module

A user interface in the Builder is called a Builder module. The Profile Tag comes with a Builder module, which allows for setting up both site-specific and page-specific configurations that map page elements to Profile tracking service calls.

Mechanics of Profile Tag

Mechanics of Profile Tag

When a site containing the Profile Tag is served to a visitor, SAP Hybris Profile Tag sends events according to the configuration of the page types. What data gets sent for a page that a user visits depends on the page types that apply to that specific page. A page can belong to zero, one, or many page types. The configuration for each page type contains a set of abstract rules to define where to get the data from within the specified page, and what tracking parameter to use those data.

Example

A tenant can have this configuration:

  • Whenever the URL of a site's page contains the string "&reviewid=", this is a Product Review Page.
  • In Product Review Pages, seek the first <h1> element of the page, split its value at the ":" character, take the first element of the resulting array and use it as the productSku.
  • In ProductDetailPageView event messages, this value will be used as productSku.

The getting started tutorial

  1. Make sure to subscribe to the right packages. To learn what packages to subscribe to, see the Prerequisites for Profile Tag section.
  2. When you open your project in the Builder, select Profile Tag in the menu on the left.
  3. Select + ADD SITE and follow the instructions in the Set up Profile Tag section.
  4. After setting up a site, you need to set up at least one new page. For more details, see the Set up a new page type section.
  5. Introduce the Profile Tag JavaScript to the pages of your site that you want to track. For more details, see the Insert Profile Tag into the website section.
  6. To check if everything works as expected, go the Builder, open the site that you created and the page you want to check. Click on START QUICK INGESTION and then TURN ON INGESTION. Next, click on the Test buttons in each row under Value Retrieval. You should see the desired values in the PREVIEW column.


Set up Profile Tag

If you use your YaaS project on one site, you need to configure only one site for the Profile Tag. If you have a second site using the same YaaS project, but the pages of the second site have the same internal HTML structure as the pages of the other site, technically you do not need a second site configured in the Profile. Nevertheless, it is recommended that you create a second site.

To set up a new site in the Profile Tag, select Profile Tag in the menu on the left, and then + ADD SITE".

Add Site

Next, specify the following details:

New Site

  • Site Name
    • The site name used in the Builder
    • Must be unique within your project
  • Consent Management
    • This setting determines how your site deals with customer consents
    • Consent management can be either implicit, or explicit:
      • Implicit consent management
        • Customer consent is assumed (opt-out). The customer does not need to express permission
        • ProfileTag proactively makes requests to the Profile to create new user-individual consent records with the tenant's default consent settings. The records are stored and used during subsequent visits
        • This setting overrides the type of consent management policy, defined for the site to which this page belongs
      • Explicit consent management
        • Customer consent is not assumed (opt-in). The customer must express permission
        • This setting overrides the type of consent management policy, defined for the site to which this page belongs
        • Add the Consent selector type that specifies how to create consents
  • Site Description
    • This setting is optional
    • It is a more detailed explanation of the purpose of a site. It is especially helpful if you have multiple sites.

When you save your changes, you are redirected to the site management page. This page contains more data and controls than the New Site page.

Edit Site

  • Configuration URL
    • This is the location where the site's configuration is stored
    • Required when you introduce the tracking code to the pages of your site
  • SAVE
    • Click this button to save the site configuration
  • DELETE SITE
    • Removes the site and its configuration
    • The delete operation is irreversible
  • Pages

All site configuration changes must be saved to take effect. Click the SAVE button on the top right.


Set up a new page type

New Page

A site usually has several different types of pages in the abstract sense, and many actual pages to be visited. This natural structure is reflected by the Page Types defined in the Profile Tag. A page can be linked to one or multiple Page Types at once, or to no Page Types at all.

Sample scenario

In this sample scenario, a store offers 500 different products. While each product has its own product detail page with a unique URL, these 500 pages have the same DOM identifiers. That is why it is sufficient to configure a single page type, named Product Detail, to enable tracking for all pages offering a detailed view of a product.

If, however, a customer performs a keyword query, the site displays a page with a different internal structure. If keyword search result pages should send events to the Profile too, configure a new page in the Profile Tag.

New Page

When creating a new page definition, supply the following information:

Name

  • The name of the page type you are creating this definition for
  • Use the vocabulary you are used to, or find a good fit
  • Examples
    • "Products overview"
    • "Detailed_Product_View"
    • "product review page"
    • "StoreSearch"
    • "Home"

Description

  • Add a description to explain what the purpose of the page is, especially if the title is not self-explanatory. This setting is optional.

Consent Management

  • Defines how this page type deals with customer tracking consents
  • Consent policy options:
    • Inherit
      • The consent settings of the site this page belongs to are applied to this page
      • Recommended setting, see the Best practices section
    • Implicit
    • Explicit

URL

  • You can supply a complete URL of a representative page of your choice for this page type
    • Examples
    - http://www.example.com/some/path/productname.html
    - http://www.example.com/store/product/12345a/Details
  • Use this page to select and test the selectors
  • You can change the URL at any time. Its sole purpose is to allow you to conveniently manage page configuration in the Builder.
  • The tracking behavior of the Profile Tag remains unaffected by the page's availability

New Page

Regular expression

  • How Profile Tag recognizes the page type gets defined here.
  • Regular expression is the pattern applied to the Object to match with Regular Expression which can be:
    • a JavaScript Object inside the top-level client side Object "window"
      • Identify the JavaScript Object by inspecting the sources and DOM Structure of your page in the browser or, if possible, have a look at your website's code directly
      • For more information about the JavaScript Object "window" see the Mozilla Developer Network
      • For more information about the DOM Tree see the Mozilla Developer Network documentation
    • The content of a DOM element inside the HTML-tags using CSS Selectors
      • Identify the CSS selector by inspecting the DOM Structure of your page in the browser or, if possible, have a look at your website's code directly
      • For more information about CSS Selectors see the Mozilla Developer Network documentation
  • Whenever a page containing Profile Tag is rendered all regular expressions detecting a page type defined in Profile Tag are evaluated
  • If there is a match, that is, if the evaluation returns the value "true", the Page Type is recognized and the corresponding events are sent
  • A single instance of a page can get recognized as several different page types simultaneously. The event settings of all Page Types are applied.
  • Standard JavaScript Syntax is used for defining regular expressions
  • For tutorials on regular expressions, see the
  • To check if a regular expression is working as expected, see the
  • Examples:

    Page TypeActual page structure characteristicsObject to match with Regular expressionRegular expression
    "Product Detail Page""/product/" in the URLlocation.href\/product\/
    "Cookie missing"In the URL, there is no text "cookie" followed by a single dollar sign and a 5 digit numberlocation.href^(?!.cookie\$\d{5}).$
    "Search Page"After clicking on the search button, the user is directed to "www.example.com/frenchStore/searchqueryterm?"; both http and https are possibledocument.referer(http|https):\/\/www.example.com\/frenchStore\/searchqueryterm\?
    "Product Detail Page"A title containing the word "Details" with a capital "D" as an attribute value.title [value]Details
    "Searched"A span element inside an element with the identifier "query" containing the text "you searched for"#query span\byou\b\s\bsearched\b\s\bfor\b\s

To take effect, all changes made to the configuration of a page type must be saved. Click the SAVE button on the top right corner of the screen.

Now that the Profile Tag knows under which circumstances it can assume that a rendered page is of a certain page type, it can analyze the details of a customer's visit to extract information enriching the customer's profile:

  • Profile Tag needs to know what events should be sent
  • An event has a number of attributes, which is represented by a map of key-value-pairs
  • Some events derive their values from the automatically created message body, therefore having no mandatory attributes to be configured
  • Other events need manual configuration to be sent via the message body. If that is the case, for every key, the Profile Tag requires information on what element or Object contains the relevant data
  • The raw data may be post-processed before being sent


Configure events

Selectors and interactions

SAP Hybris Profile uses events, which are messages that contain data from a tracked page and visitors. SAP Hybris Profile processes the event data to enrich a visitor's profile.

A trigger prompts these event messages to send. SAP Hybris Profile differentiates between events that occur while the page is loaded, which you configure using selectors, and events that can occur after the page is loaded, which you configure using interactions. All events, regardless of the trigger, must contain meaningful data in the message body. You can configure the Profile Tag to send any data from the page as properties in the body, be it from a DOM element, a JavaScript object, cookie, or a static value.

New Page

To edit the existing selectors and interactions, click the relevant row of the respective list.

Selectors

Selectors allow you to define data that SAP Hybris Profile Tag extracts from a website every time this website is loaded. This section explains how to add, edit, and remove selectors as well as the configurable paramaters of selectors and their effects.

Create a new selector

To configure a new selector:

  1. Click ADD SELECTOR. A configuration window opens.
  2. Add properties to an existing event, or configure a new event. See Fields to configure for more details.
  3. Click SAVE in the bottom-left corner of the window. The window closes.

To let your changes take effect:

  1. Click SAVE in the top-right corner of the screen.
  2. Click BACK in the top-left corner of the screen.
  3. Click ROLL OUT in the top-right corner of the screen.

Fields to configure

Specify the data that you send in the body of an event. In particular, you must define these elements:

  • Key
  • Selector
  • Attribute
  • Type
  • Post-processing functionality and parameters

On Page Load event

Delete selectors

Deleting a selector is an irreversible operation, which means that you would need to re-enter the data if necessary.

To delete a selector:

  1. Click DELETE.
  2. Click the SAVE button in the top right corner to make the deleted operation take effect.

Test selectors

Currently, testing works only for a selector of the type Text, added using ingestion. This operation outputs the value, in the form in which it is sent, as an event to SAP Hybris Profile. It includes post-processing steps, if given.

To test a selector:

  1. Click START QUICK INGESTION.
  2. Click TEST.
  3. See the output in the PREVIEW column.

Selector.Key

Keys act as names, and accordingly, as identifiers for the properties to send in the message body. You can send data either within the generic PageView event or within specific, predefined events.

  • Provide certain, reserved keys to create specific events implicitly.
  • Fill in all of these reserved keys with non-empty string values to trigger the respective, specific event.
  • If a key is not in the list of reserved keys, it is appended to the generic PageView event.

The following table shows a list of specific events and reserved keys.

Event TypeReserved keys to create event
PageViewnone
ProductDetailPageViewproductSku (stock-keeping unit, the shop-wide unique identifier of the product)
productName
productCategory
productPrice
CategoryPageViewproductCategory
SearchsearchTerm
productCategory (optional and, if provided, the predefined logic uses it)

Selector.Selector

When configuring a selector, define the Selector field to indicate where to collect the data from. The syntax of retrieving data from the page depends on the type you select.

Selector.Type

There are various sources where you can retrieve the data to be sent. Select the appropriate type of data source according to the structure of the page. This means that you can obtain the values from the following sources or actions:

  • the DOM tree using CSS selectors
  • reading from a JavaScript object inside the top-level client-side object window
  • reading the visitor's cookie
  • sending a static string

For more information about:

Different selector types in detail

SAP Hybris Profile supports different types of selectors, from simple constant values, to extracted data from the DOM of a website, or even user's cookies.

DOM tree elements using CSS selectors

By using CSS selectors, you can extract the inner Text, the inner HTML content, or DOM-Attributes of an element.

Text
  • Include only plain text inside the opening and closing HTML tags of the DOM element
  • Removes the opening and closing HTML tags of the element
  • Removes HTML tags from the nested tags

Example:

<div id="demo"><a href="url">My text</a></div>
<script>
var x = document.querySelector("#demo").innerText; // The value of x is "My text"
</script>
DOM element

The DOM element:

  • includes the entire content of the DOM element and the opening and closing HTML tags of the DOM element
  • does not remove any tags, either from the element itself, or from the nested tags, if applicable
  • omits HTML attributes (for more information about HTML attributes, see the Mozilla Developer Network documentation)

Example:

<div id="demo"><a href="url">My text</a></div>
<script>
var x = document.querySelector("#demo"); // The value of x is Html DOM Element <div><a>My text</a></div>
</script>
HTML

HTML:

  • includes the entire content of the DOM element but without the opening and closing HTML tags of the DOM element
  • removes tags from the element itself but not from the nested tags, if applicable
  • omits HTML attributes (for more information about HTML attributes, see the Mozilla Developer Network documentation)

Example:

<div id="demo"><a href="url">My text</a></div>
<script>
var x = document.querySelector("#demo").innerHTML; // The value of x is "<a href="url">My text</a>"
</script>
Identify the CSS selector

There are multiple ways to identify the DOM tree element to select.

Inspect the page or code

As described in the Regular expression section, the usual procedure for identifying the DOM tree element to select is as follows:

  1. Inspect the page in the browser or, if possible, look at the code directly.
  2. Click ADD SELECTOR.
  3. Enter the correct CSS selector into the Selector field.
Use ingestion

For DOM elements of the type Text, DOM Element and HTML there is an alternative way using the Ingestion Mode. This approach adds a new selector without clicking ADD SELECTOR.

There are two prerequisites for this approach:

  1. You must add the Profile Tag JavaScript part to the sample page as explained in the Insert Profile Tag into the website section.
  2. The sample page must use the jQuery library.

To identify the CSS selector using this approach:

  1. Click START QUICK INGESTION. The page specified in URL field of the page loads inside the preview window in an embedded fashion.
  2. Decide which DOM tree element to select by looking at that page. You can also open the page in a separate browser tab if you feel restrained by the small preview window.
  3. When you make your decision, click TURN ON INGESTION. This switches from the regular mode to the ingestion mode.
  4. Hover over the page to see the DOM tree elements highlighted with red rectangles, which means that you can select them.
  5. Click a highlighted element to select it. The selected DOM identifier of that element is added to the list of selectors.
  6. Complete the configuration of the selector by clicking on the row of the corresponding selector in the list of selectors.
JavaScript as the type of data source

The JS variable reads from a JavaScript object inside the top-level client-side object window.

See the Mozilla Developer Network documentation for further details.

Write the name of the function in JavaScript syntax just like you would call it in the code, including round brackets and parameters, if needed. The returned value can be an array, an object, a string, or a number. To receive meaningful data, SAP Hybris Profile Tag requires simple values, otherwise, it cannot process the data. The array or object must be post-processed to extract the relevant simple value, such as a string.

Example:

<script>
var x = window['location']; // the value of x is "https://www.example.com/search?cool+item"
</script>

For further details, see the Post-processing function and parameters section.

To use a cookie as the data source type, complete the Selector field with the exact name of the cookie.

For more information about cookies, see the Mozilla Developer Network documentation.

Example:

With JavaScript, you can create a cookie like this:

document.cookie = "username=John Doe";

To retrieve the value of the cookie, complete the Selector field with the name of the cookie username

You need this type of selector if consent management for the page is set to explicit, either directly, or by inheritance from the consent management setting of the site. If this is not the case, this selector is ignored.

To use the consent selector type, fill in the Selector field with the exact name of the cookie.

For more information about cookies, see the Mozilla Developer Network documentation.

This selector type checks the visitor's cookie for a consent reference. If no consent is found, SAP Hybris Profile Tag sends one by executing a POST request to the Consent service to obtain a new consent reference with the tenant's default settings. You can configure a Consent granted page so only users referred to that page by clicking OK get a consent reference.

Other types of data sources

In addition, SAP Hybris Profile supports two other selector types.

Constant

Use this type to submit a static value with each event to SAP Hybris Profile. To do so, enter the string in the Selector field.

GTM Data Layer

When your page uses the Google Tag Manager (GTM), you can configure Profile Tag to access the JavaScript variables defined in the GTM data layer. To do so, enter the name of the variable, which is case-sensitive, in the Selector field. The Attribute field in this case is ignored.

Selector.Attribute (optional)

This optional selector reads the value from the HTML attribute. It is only applicable for a selector of the type DOM Element.

Example:

Setting Attribute to src with the img tag

<img src=www.example.com/example.png>

results in Profile Tag obtaining and sending www.example.com/example.png, assuming it has no post-processing in place.

For more information about HTML attributes, see the Mozilla Developer Network documentation.

Post-processing functions and parameters (optional)

There are several possibilities to process values that are captured by your selectors before Profile Tag feeds them into SAP Hybris Profile. The following picture highlights the post-processing configuration section.

On Page Load event - Post-processing

To add post-processing steps:

  1. Choose a function from the Function dropdown list.
  2. Set Parameter to a certain value, if the function takes this value as a parameter. Otherwise leave it empty.
  3. Click ADD.
  4. Repeat steps 1-3 for more post-processing steps.

For more information about post processing options and their functions and parameters, see the Post-processing function and parameters section.

Interactions

How the visitor interacts with the page after the page renders can be the starting point for sending events to SAP Hybris Profile, too. This way, the service can register a click on a button that does not make the page reload. Define the key, selector, and attribute properties to send, and the schema that determines how to send the data to SAP Hybris Profile, according to your needs. Additionally, an interaction can contain a list of mappings where each mapping contains data collected from different DOM elements.

interaction

Create a new interaction

To configure a new interaction:

  1. Click ADD INTERACTION. A configuration window opens.
  2. Add properties to an existing event, or configure a new event. See Fields to fill in and List of Mappings for more details.
  3. Click SAVE in the bottom-left corner of the window. The window closes.

To let your changes take effect:

  1. Click SAVE in the top-right corner of the screen.
  2. Click BACK in the top-left corner of the screen.
  3. Click ROLL OUT in the top-right corner of the screen.

Fields to fill in

FieldsDescription
Event nameThe freely defined name for the event.
DOM-elementSelect a DOM-element, as described in the Selector.Type section, which triggers the event.
Event on that DOM-element to listen toUses DOM events. For more information about DOM events, see the Mozilla Developer Network documentation.
Examples: click, mouseover
Schema to sendEither use one of the predefined event schemas to send as an interaction, or define your own.
When configuring an interaction on your own, without referencing one of the reserved interaction Schemas, keep in mind that an enricher needs to catch and process these attributes to be able to enrich a profile.
Predefined events:
  • are based on an already registered schema
  • require all mandatory attribute values before sending the events
  • are stored by SAP Hybris Profile using existing logic according to the schema definition
  • are extendable, allowing you to add more attributes according to your needs

List of Mappings

FieldsDescription
Keystates the name of the attribute to send to SAP Hybris Profile, for example: cartID, searchTerm, videoTopic.
Selectorstates the HTML DOM element from which to read the data
Attributestates where to get the data from within the HTML DOM element using the HTML DOM attribute notation, such as:
  • data-topic when having a div element like the following to get the String title as the value for an attribute <div data-topic="icecream">...</div>
  • myTitle of the following header DOM element to get the String Do you enjoy headings? as the value for an attribute:
    <h1 myTitle="Do you enjoy headings?"></h1>

Example:

Your web page contains the following markup and you want to send an event that contains videoTopic: coolMovie.mp4.

<video width="320" height="240" controls>
  <source src="coolMovie.mp4" type="video/mp4">
</video>

To achieve that:

  1. Enter source into the Selector field (because coolMovie.mp4 is a component of the source tag of your markup).
  2. Enter src into the Attribute field (because within the source tag, the src attribute is the relevant one).
  3. Enter videoTopic into the Key field (because that is the key you want the sent event to contain).
  4. Click ADD MAPPING.

This is a list of the reserved schemas and their required attributes:

Schema to sendMandatory Attributes
AddToCartcartID the identifier of the visitor's shopping cart
productName
productSku stock-keeping unit: the shop-wide unique identifier of the product
productPrice
qty quantity: defaults to 1, if not set
productCategory
ChangeQuantityInCartsee the AddToCart event
RemoveFromCartsee the AddToCart event
KeywordSearchsearchTerm
productCategory
VideoInteractionnone
Downloadnone
Outlinknone

When you finish configuring an event or an interaction, or you edit a page type in any other way, click SAVE in the top-right corner to make your changes permanent.

Post-processing functions and parameters (optional)

There are several possibilities to process values that are captured by your interaction mappings before Profile Tag feeds them into SAP Hybris Profile.

Assume there is already a certain interaction defined, as well as a mapping from a key key to the selector #selector. The list of mappings contains this mapping. A click on the key highlighted in blue unfolds the postprocessing options. The following picture shows that situation.

Interaction mapping - Post-processing

To add post-processing steps:

  1. Choose a function from the Function dropdown list.
  2. Set Parameter to a certain value, if the function takes this value as a parameter. Otherwise leave it empty.
  3. Click ADD.
  4. Repeat steps 1-3 for more post-processing steps.

For more information about post-processing options and their functions and parameters, see the Post-processing function and parameters section.

Post-processing functions and parameters

Sometimes taking the value of a selector and using it 1:1 in the generated payload is a suboptimal solution. SAP Hybris Profile also needs simple values, i.e. strings, to process data. Therefore you can specify a list of post-processing steps. The steps run one after another, like a stack of papers with each paper containing an instruction, i.e. the order of these post-processing steps matters.

To insert a post-processing step between two already existing steps, or to add a step before an existing step, delete all post-processing steps and start over from scratch.

To retain the settings used previously, take a screenshot of your existing work and reference it when configuring the new list of steps.

With the post-processing inside the Builder module, you can alter the string, array, and object values.

Simple value post-processing with JavaScript methods

Post-processing regarding simple values is based on the selected standard JavaScript String methods.

For more information about JavaScript String methods, see the Mozilla Developer Network documentation.

Trim

trim removes leading and trailing whitespaces. The value remains a simple value.

Example:

var str = "       Hello World!        ";
var x = str.trim();     // the value of x is "Hello World!"
Split

split requires a non-empty, non-whitespace string as a split pattern in the field Parameters. The string is converted to an array. Use array methods after using the split method to manipulate the result further, for example by using a combination with pop or shift.

Example:

var txt = "a,b,c,d,e";   // String
txt.split(",");          // Split on commas
txt.split(" ");          // Split on spaces
txt.split("|");          // Split on pipe

Array post-processing with JavaScript methods

Post-processing regarding arrays is based on the selected standard JavaScript array methods.

As explained in the JavaScript as the type of data source section, you must post-process a JavaScript array or object to extract the relevant simple value, whether it is a string or a number. Because an array can be nested, that is, contain arrays as elements, you might need to apply post-processing several times to allow Profile Tag to use the data.

For more information about JavaScript array methods, see the Mozilla Developer Network documentation.

Shift

shift returns the first element of an array and does not take parameters.

Example:

var arr = ["a", "b", "c", "d"];
var x = arr.shift();     // the value of x is "a"
Pop

pop returns the last element of an array and does not take parameters.

Example:

var arr = ["a", "b", "c", "d"];
var x = arr.pop();      // the value of x is "d"

Object post-processing

Use the map_get function for object post-processing. This function requires the selector to be an object at this point of the post-processing chain.

JavaScript objects are technically maps, where the stored data is called attributes. Each attribute has a value and a name, known as the key. Using the key, you can reference and obtain the desired value. Put the key inside the Parameter field.

JavaScript objects can contain multiple layers, which means that you can nest them, just like an HTML tag can contain more HTML tags inside of it. They can also contain arrays. Because of this, you might need to use map_get multiple times, or array methods, to obtain simple values.

For more information about JavaScript objects, see the Mozilla Developer Network documentation.

Example:

var myMap = {"key1": "value1", "key2": "value2"};
var x = myMap["key1"];      // the value of x is "value1"

Post-processing combination examples

Combining post-processing steps together can be quite powerful to fulfill certain use cases. The following examples demonstrate some selector possibilities. They work for post-processing mapping results in interactions, too.

String and array post-processing example

If you want to take the productSku from the title of the page using the selector type text, but your page titles are constructed as follows: ProductSKU + ' - ' + ProductName + ' - ' + YourShopName, take the page title and do some post-processing to cut away the unnecessary parts. Select the first element as shown in the example.

Example:

  1. Add a split function with the Parameter -. This creates an array containing three simple values: ProductSKU, ProductName, and YourShopName.
  2. Add the pop function. This will obtain the last value, ProductSKU, a simple value usable by SAP Hybris Profile.

post-processing-example-1

Object post-processing example

If you want to obtain the year a customer was born in, and the JavaScript object for the customer you obtained has the following structure, use the following procedures to get the birth year.

{ "customer": {
    "contactInformation": {
        "firstName": "Groucho",
        "lastName": "Marx".
        "birthday": "1890/10/2"
    },
    "productsBought": {
        "product:" [
            {"name": "glasses", "category": "eyeglasses and sunglasses", "sku": "12345"},
            {"name": "cigar", "category": "foodstuffs, drinks and tobacco", "sku": "23456"},
            {"name": "mustache", "category": "other", "sku": "34567"},
            {"name": "eyebrowes", "category": "other", "sku": "45678"},
        ]
    }
 }
}

To obtain the customer's birth year, access the contactInformation value by its key, using the map_get function. Use that function again with birthday as a parameter, then use split the resulting string by /, and finally use pop to get just the year.

  1. Add a map_get function with the Parameter field set to contactInformation.
  2. Add a map_get" function with the Parameter field set to birthday.
  3. Add a split function with the Parameter field set to /. This splits the simple value into an array with three elements.
  4. Add a shift function. This gets the first element.

post-processing-example-2

The result is the simple value 1890 sent with the generic PageView event.


Insert Profile Tag into the website

Include the JavaScript Tag in the code for each web page, or web page template. Edit the JavaScript Tag before inserting it into your web page code:

<script>
    (function () {
        window.Y_TRACKING = window.Y_TRACKING || function () {
            (window.Y_TRACKING.q = window.Y_TRACKING.q || []).push(arguments);
        };
        var s = document.createElement('script');
        s.type = 'text/javascript';
        s.async = true;
        s.src = {profile Tag URL};
        var x = document.getElementsByTagName('script')[0];
        x.parentNode.insertBefore(s, x);
    })();
    window.Y_TRACKING({tenant: '{tenant ID}', clientId: '{Client ID}', configUrl: '{Config Url}'});
</script>
  • Replace the {tenant ID} with the Identifier value of your Builder project. In the Builder, select {Your Project}, and click Administration in the left navigation column. Next, click Details in the left navigation column, and copy the value of the Identifier.
  • Replace the {Client ID} with the Identifier value of the appropriate client. In the Builder, select {Your Project}, and click Clients in the left navigation column. Then, select the appropriate client, and copy the value of the Identifier.
  • Replace {Config Url} with the value of the Configuration URL, for example https://s3.amazonaws.com/profile-tag/58d934c9974013000ec3e2fb.
  • Replace the {profile Tag URL} with a link from Profile Tag links. This explains which URL to use according to your specific scenario.
If your website is not using the Https protocol, add the allowInsecureCookies:true parameter to the initialization call, as shown in the following example.
<script>
    (function () {
        window.Y_TRACKING = window.Y_TRACKING || function () {
            (window.Y_TRACKING.q = window.Y_TRACKING.q || []).push(arguments);
        };
        var s = document.createElement('script');
        s.type = 'text/javascript';
        s.async = true;
        s.src = {profile Tag URL};
        var x = document.getElementsByTagName('script')[0];
        x.parentNode.insertBefore(s, x);
    })();
    window.Y_TRACKING({tenant: '{tenant ID}', clientId: '{Client ID}', configUrl: '{Config Url}', allowInsecureCookies:true});
</script>


Decide which Profile Tag link to use

For the Profile Tag, major versions, minor versions, and patches are released in all available zones. Three digits, such as x.y.z, represent these versions of the Profile Tag. X stands for the major version, y for the minor version, and z for the patch version. The Profile Tag has eight URLs available. The following sections explain when to use each of those links.

These links point to the US server.

These links point to the EU server.

Which URLs to use

It is recommended that you use the URLs for the latest version of the Profile Tag. To test your application before using a changed version of the Profile Tag, use a specific major, minor, or patch version explicitly, and switch to a new version of the Profile Tag if your tests succeed.

Release Notes published in the Dev Portal explain new version changes with every release of the Profile Tag service.


Consent management setting

SAP Hybris Profile tracks only those types of information for which the consumer or the tenant grant consent. If a website tracks the customers' activities, legal regulations in most countries make it necessary to inform the customer about the tracking, and guide the customer to a page containing further details.

If you want SAP Hybris Profile to track the customer's activities using default consent settings, set the consent management setting to implicit. The system then assumes that the customer's consent exists.

If SAP Hybris Profile is supposed to track the customer's activities only after the customer explicitly expresses consent, set the consent management setting to explicit. You need to generate a consent reference for such a customer in a separate call as soon as the customer grants consent, for example by clicking on the tracking acknowledgement button.

The Profile Tag allows different consent management settings for each page. For more details about consent management, see the Set up Profile Tag and Set up a new page type sections.


Sample setup tutorial

To introduce and set the configuration of the Profile Tag to a shopping site, you can use YaaS storefront. The setup of YaaS storefront is explained in the YaaS Devportal.

The Profile Tag can be integrated with any website, not just with YaaS storefront.


Best practices

  • Try to minimize your efforts. If you have several different page types which all are supposed to send the same events, create a single page type in the Profile Tag instead.
  • If the page already has meta information in JavaScript, use it.
  • If possible, use those elements of the page that are least likely to change at a redesign as attribute values.


Quick start guide

This section shows how easy it is to start working with SAP Hybris Profile. The document provides step-by-step instructions on how to make use of Profile's primary functionality, which is collecting data pertaining to user activity in the storefront. After reading this chapter, you will be able to:

  • make a YaaS account, create an organization, and create a project, all of which you need to start using SAP Hybris Profile
  • subscribe to the appropriate packages
  • download the simplified storefront project and parameterize it with your tenant
  • use the storefront to send events to SAP Hybris Profile
  • use the Trace Explorer to track events created by user activity in the storefront
  • use the Graph Explorer to see the visualization of the graph changes caused by user activity in the storefront

Start using SAP Hybris Profile in just six steps!


Step 1: Create and configure a YaaS account

This section explains how to create a YaaS account, an organization, and a project.

Create a YaaS account

To create a YaaS account, follow these steps:

  1. Go to the YaaS main page.
  2. Select Register for free and follow the steps provided in the instructions to complete the registration.

Create an organization

When your registration is complete, you can create your own organization.

If you wish to start using SAP Hybris Profile, creating an organization is mandatory.

To set up your organization, follow these steps:

  1. Sign in to the Builder using your YaaS account.
  2. Select Create your own organization.
  3. Provide the name of your organization.
  4. Select your country of origin.
  5. Click Try for free to create a non-commercial organization.
    To read more about the commercial organization, go to the Create an Organization section.

Create a project

To start using SAP Hybris Profile, you need a project, also known as a tenant. Follow these steps to set up your project:

  1. In the Builder, select your organization and click Create your first project.
  2. Complete the Display Name and Identifier fields to define your project. Optionally, provide the description of your project.
  3. Click Save to create your own project.


Step 2: Subscribe to packages

To use SAP Hybris Profile as described in this document, subscribe your project to the following packages:

  • Profile Core Services
  • Profile Services for Commerce

To subscribe to the Profile Core Services and Profile Services for Commerce packages, follow these steps:

  1. In the Builder, select {Your Organization} > {Your Project}.
  2. Navigate to {Administration} > {Subscriptions}.
  3. Click Subscribe. The YaaS Market opens.
  4. Find the Profile Core Services and Profile Services for Commerce packages.
  5. To subscribe to the packages, click on the icons representing each, and select Subscribe now.
  6. Select a project to subscribe to the packages, and click Continue.
  7. Review your order and click Subscribe now.


Step 3: Set up a simplified storefront

To start using SAP Hybris Profile for the purpose described in this document, you need a storefront. For your convenience, it is recommended that you download and install a simplified storefront version created specially to introduce you to the basic SAP Hybris Profile functionality. The simplified storefront project is located here.

To download and install the simplified storefront, and parametrize it with your tenant, execute the following commands. Replace the {tenant} parameter with your tenant identifier.

You must have npm and Git installed locally. For more information about installing Git, see Prerequisites. For more information about installing npm, see the npm official documentation.
git clone -b SAP_Hybris_Profile_Quickstart https://github.com/hybris/yaas-storefront-profile-quickstart.git
cd yaas-storefront-profile-quickstart
npm install
npm start -- --pid={tenant}

If you are located in the EU region, modify the last command to look as follows:

npm start -- --pid={tenant} --region=eu

After executing these commands, open the storefront in your browser by clicking the following link: http://localhost:9000.

Use this storefront to send basic events such as PageViewEvent and ProductDetailPageViewEvent to SAP Hybris Profile, track the events in the Trace Explorer, and see the visual representation of the graph changes caused by the events in the Graph Explorer. For more complex operations, use the YaaS Storefront. For more details about the YaaS Storefront, and how to set it up, see the Getting Started guide.


Step 4: Send events

Now that the simplified storefront is installed locally on your machine and ready to use, you can send events to SAP Hybris Profile just by clicking on the storefront.

The simplified storefront supports two event types only: PageViewEvent and ProductDetailPageViewEvent.

Interactions with the storefront create events. Open or refresh the storefront website to create a PageViewEvent, or click on the product of your choice to create a ProductDetailPageViewEvent. The enrichers contained within the Profile Services for Commerce package that your tenant is subscribed to react to these events, and introduce changes to the graph, for example by creating nodes or relationships.


Step 5: Track events

You can track the events sent from the storefront to SAP Hybris Profile in the Trace Explorer. Tracking allows you to collect details about the exact time of calls between services, and the duration of specific operations. Additionally, it allows you to detect any latency problems.

In the simplified storefront version, tracing is enabled by default. Therefore, no action from you is required to activate event tracking.

To navigate to the Trace Explorer, click a contextTraceId link that appears at the top of the screen each time the storefront sends an event to SAP Hybris Profile.


Step 6: View the graph changes in the Graph Explorer

The events that you send to SAP Hybris Profile from your storefront trigger the enrichers. Depending on the event type, the triggered enrichers introduce various changes to the profile graph.

For example, by clicking on a product in the storefront, you send the ProductDetailPageViewEvent to SAP Hybris Profile. This event triggers the specified enricher, which modifies the graph database by creating nodes and/or relationships, such as a VIEWED relationship between the Session and the Product nodes.

Follow these instructions to see a visual representation of the graph modifications associated with the Profile node.

  1. Go to the Trace Explorer to see the initial logs from context adapters that pre-process the event sent from the storefront before dispatching it to the enrichers.
  2. In the Context Transition component of the Trace Explorer, click one of the displayed links, which represent a given contextTraceId. Each storefront event triggers various enrichers. What you see is a list of enricher-generated logs resulting from the storefront activity.
  3. Find the log with a message about node creation that displays the schema nodes/commerce/Session. The log indicates that an enricher created a node defined by the schema nodes/commerce/Session.
  4. Click the nodes/commerce/Session link to go to the Graph Explorer and view the created nodes and relations in a visualized form.
  5. Find the node Identity, and double-click it. Double clicking loads more data dynamically.
  6. See the node for Profile. Hover your mouse over the node to display the node's details, or click the node to display them under the graph.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.