Piwik

Overview

The Piwik service is a Context Adapter that provides a REST interface to receive user-action data from the Piwik UI library and store this data in the SAP Hybris Profile system through the context service.

The JSON data processed by the Piwik service includes an action_name attribute whose value can be one of the following self-descriptive strings:

  • AddToCartEvent: Associated with the context/commerce/AddedToCart schema.
  • CategoryPageViewEvent: Associated with the context/commerce/CategoryView schema.
  • CustomerLogin: Associated with the context/core/LoggedIn schema.
  • KeywordSearchEvent: Associated with the context/commerce/KeywordSearch schema.
  • PageViewEvent: Associated with the context/commerce/FrontendEntered schema.
  • ProductDetailPageViewEvent: Associated with the context/commerce/ProductView schema.

For details about the Piwik JSON message structure, see the Piwik Tracking API documentation.

The Piwik service supports the following content type:

  • application/json

API Reference

/{tenant}/events

/{tenant}/events

post

Processes and stores user-action data from the Piwik UI library. See the Piwik Tracking API documentation for details.

Processes and stores user-action data from the Piwik UI library. See the Piwik Tracking API documentation for details.

URI Parameters

  • tenant: required (string)

    The tenant string is the value of the project's Identifier from the Builder.

Headers

  • consent-reference: required (string - pattern: ^[a-zA-Z0-9_-]*$)

    The identifier of the caller's consents. Single consent reference is some abstract identifier which is attached to the requests incoming the Profile. This identifier represents the consents which were voluntarily agreed by the user. It represents several different aspects of user interaction with storefront to be collected and upon which some conclusion can be issued to improve user's experience.

  • Authorization: required (string)

    Used to send a valid OAuth2 access token.

    Example:

    Bearer access_token

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "action_name": {
            "type": "string",
            "description": "Describes the type of action to be taken",
            "example": "AddToCartEvent|CategoryPageViewEvent|CustomerLogin|KeywordSearchEvent|PageViewEvent|ProductDetailPageViewEvent"
        },
        "idsite": {
            "type": "string",
            "description": "The ID of the website being tracked"
        },
        "rec": {
            "type": "string",
            "description": "Required for tracking; must be '1'",
            "example": "1"
        },
        "url": {
            "type": "string",
            "description": "The full URL for the current action"
        }
    },
    "required": [
        "action_name",
        "idsite",
        "rec",
        "url"
    ]
}

Example:

{
    "action_name": "ProductDetailPageViewEvent",
    "idsite": "1",
    "rec": "1",
    "r": "469869",
    "h": "13",
    "m": "1",
    "s": "51",
    "url": "http://somestore.yaas.io/#!/products/550179c138ae86edc6725ef7/",
    "_id": "93337f761afbab86",
    "_idts": "1425374194",
    "_idvc": "18",
    "_idn": "0",
    "_refts": "0",
    "_viewts": "1426090398",
    "_ects": "1425390712",
    "pdf": "1",
    "qt": "0",
    "realp": "0",
    "wma": "0",
    "dir": "0",
    "fla": "1",
    "java": "1",
    "gears": "0",
    "ag": "1",
    "cookie": "1",
    "res": "1920x1200",
    "cvar": "{\"2\":[\"_pkp\",110],\"3\":[\"_pks\",\"lumia920\"],\"4\":[\"_pkn\",\"Nokia Lumia 920\"],\"5\":[\"_pkc\",\"Phones\"]}",
    "gt_ms": "13"
}

HTTP status code 201

The request has been fulfilled and resulted in a new resource being created.

Headers

  • Location: (string)

    URI of created resource.

HTTP status code 400

Body was in incorrect format.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

HTTP status code 401

Given request is unauthorized. Bad or expired token. Reauthenticate the user. Any details will be provided within the response payload.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

Example:

{
    "status": 401,
    "message": "Authorization: Unauthorized. Bearer TOKEN is invalid",
    "type": "insufficient_credentials",
    "moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}

HTTP status code 403

Evaluated request scopes in access token are not sufficient and do not match required scopes.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

Example:

{
    "status": 403,
    "message": "Given request does not have required scopes in access token. It is not authorized to perform this operation.",
    "type": "insufficient_permissions"
}

Input

The Piwik UI Library sends data in the JSON format to the Piwik service, which processes the message, extracts the crucial data, and moves it to the main level of the JSON. Subsequently, it outputs the data in the JSON format. For an example of an output message, see the Output section.

This example shows a sample input message that the Piwik service receives:

{
  "action_name": "ProductDetailPageViewEvent",
  "idsite": "1",
  "rec": "1",
  "r": "469869",
  "h": "13",
  "m": "1",
  "s": "51",
  "url": "http://somestore.yaas.io/#!/products/550179c138ae86edc6725ef7/",
  "_id": "93337f761afbab86",
  "_idts": "1425374194",
  "_idvc": "18",
  "_idn": "0",
  "_refts": "0",
  "_viewts": "1426090398",
  "_ects": "1425390712",
  "pdf": "1",
  "qt": "0",
  "realp": "0",
  "wma": "0",
  "dir": "0",
  "fla": "1",
  "java": "1",
  "gears": "0",
  "ag": "1",
  "cookie": "1",
  "res": "1920x1200",
  "cvar": "{\"2\":[\"_pkp\",110],\"3\":[\"_pks\",\"lumia920\"],\"4\":[\"_pkn\",\"Nokia Lumia 920\"],\"5\":[\"_pkc\",\"Phones\"]}",
  "gt_ms": "13"
}

The attributes action_name, and those grouped in the cvar attribute, such as _pkp, _pks, _pkn, and _pkc, are custom attributes. For the description of the custom attributes, see the Output section.

The other attributes are standard parameters that the Piwik service supports. For more details, see the Piwik Tracking API documentation.

Output

The Piwik service outputs a JSON message which is cached in the Context Repository for retrieval by enrichers. An enricher which processes this JSON must explicitly respond to the action value listed in this JSON.

In the output JSON, the valid action value is determined by the action_name of the initiating Piwik request's JSON, as follows:

Input action_nameSchemaOutput action
KeywordSearchEvent...context/commerce/KeywordSearch...keywordsearch
PageViewEvent...context/commerce/FrontendEntered...storetemplate
CategoryPageViewEvent...context/commerce/CategoryView...viewcategory
ProductDetailPageViewEvent...context/commerce/ProductView...viewproduct
AddToCartEvent...context/commerce/AddedToCart...addtocart
CustomerLogin...context/core/LoggedIn...customerlogin

Click the schema name to see which enrichers are triggered by it.

All the output actions are stored as events in Context service

The following shows the structure of the Piwik service's output JSON, and includes example attribute values:

{
"res": "1920x1200",
"res_height": 1200,
"_pkc": "Phones",
"_profile_custom": {},
"ipAddress": "10.36.3.95",
"source": {
  "action_name": "ProductDetailPageViewEvent",
  "idsite": "1",
  "rec": "1",
  "r": "469869",
  "h": "13",
  "m": "1",
  "s": "51",
  "url": "http://somestore.yaas.io/#!/products/550179c138ae86edc6725ef7/",
  "_id": "93337f761afbab86",
  "_idts": "1425374194",
  "_idvc": "18",
  "_idn": "0",
  "_refts": "0",
  "_viewts": "1426090398",
  "_ects": "1425390712",
  "pdf": "1",
  "qt": "0",
  "realp": "0",
  "wma": "0",
  "dir": "0",
  "fla": "1",
  "java": "1",
  "gears": "0",
  "ag": "1",
  "cookie": "1",
  "res": "1920x1200",
  "cvar": "{\"2\":[\"_pkp\",110],\"3\":[\"_pks\",\"lumia920\"],\"4\":[\"_pkn\",\"Nokia Lumia 920\"],\"5\":[\"_pkc\",\"Phones\"]}",
  "gt_ms": "13"
},
"sessionId": "93337f761afbab86",
"url": "http://somestore.yaas.io/#!/products/550179c138ae86edc6725ef7/",
"res_width": 1920,
"_pks": "lumia920",
"_pkn": "Nokia Lumia 920",
"action": "viewproduct",
"_pkp": 110,
"user": "mustermann@hybris.com"
}

Attributes:

  • res: resolution
  • res_height: resolution height
  • _pkc: category name
  • ipAddress: IP address from which the request was sent
  • sessionId: ID of the session; converted from the *_id attribute
  • url: link pointing to where the request was sent from
  • res_width: resolution width
  • _pks: product ID
  • _pkn: product name
  • action: type of action; converted from the action_name attribute. For the list of supported actions, see the Overview section.
  • _pkp: product price without the currency
  • user: email address of the logged-in user

Metamodel

The following interactive graphic displays the routing of incoming messages triggered by a FrontendEntered event.

Glossary

TermDescription
PiwikOpen-source Web Analytics software that enables statistical analysis of web events.
authorizationThe process of determining whether a given microservice has permission to gain consent.
consentPermission to access (read, write) specific profile data, for example, permission to read/write age estimation or physical address. A consumer and a tenant can grant and revoke consent for subsets of their respective data.
consent classA string alias, defined by developers, that references a set of profile data (also called "schemas") for which consent can be granted and revoked. This string is exposed to users (consumers and tenants) as a reference through which they control consent. For example, the consent class "Purchases" might reference a set of data that includes items purchased, purchase dates, and purchase prices. Toggling consent for "Purchase" would enable and disable consent for that entire set of data.
consent referenceA unique, randomized string that serves as a passcode to decrypt data associated with one or more schemas. Various service calls require a consent reference.
consumerThe end user whose actions yield profile data in the graph. A profile describes a single consumer.
contextData that affects the state of the graph. This data can be collected from consumer-triggered events or from third-party sources such as weather stations.
Context AdapterA microservice that receives data and, optionally, adapts it for entry into the graph. For example, a context adapter can adapt address data by adding a ZIP code and normalizing the street labels (for example, changing "St" to "Street"). The Context Adapter then passes the data through the Context service, which caches it so that enrichers can subsequently persist the data in the graph.
context repositoryA temporary cache for adapted context data, before it is further processed by enrichers and persisted in the graph.
context serviceAn internal microservice that manages the insertion of, and the retrieval of, context data in the Context Repository.
encryption keyA unique, randomized string used to encrypt and decrypt specific data in the graph. Each data element is encrypted with a different encryption key. Decryption, using this key, is required to access, view, and alter the data.
enricherA microservice that retrieves data from the Context Repository and/or Graph, possibly alters or extends it, and then persists data in the graph. An enricher can interpret data points, or sets of data points, to yield new data to persist. For example, an enricher can interpret purchasing data and contemporaneous weather station data to yield new data indicating that the consumer is a rainy-day shopper.
graphThe database that stores profile data as nodes, edges, and properties, and allows semantic queries.
identityOne of many independent units of data used to identify a unique profile, such as an email address, browser type, or version.
profileData about a single consumer, collected and derived from events that are triggered by, or are logically associated, with that consumer.
schemaA string representation of a path in the graph that represents an abstraction, rather than a concrete instance, of a particular data structure.
tenantA registered entity with a shared commercial goal that subscribes to SAP Hybris Profile services and packages to reach that goal. A tenant can also develop and contribute enrichers and context adapters to the SAP Hybris Profile suite. Within YaaS, a tenant is a project.

  • 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.