Configure Universal Pixel Integration Addon - Bloomreach Experience Manager (PaaS/Self-Hosted) - The Fast and Flexible Headless CMS

Configure Universal Pixel Integration Addon

This Bloomreach Experience Manager feature requires a standard or premium license. Please contact Bloomreach for more information.

The Universal Pixel Integration addon utilizes the ChannelInfo Mixin feature to allow webmasters and editors to configure the Universal Pixel integration in the Experience manager. Also, a project may define custom Universal Pixel variables by setting custom JSON schema resource(s). If custom JSON schema resource(s) are configured, the custom variables in the custom JSON schema resource(s) will be shown in the editor UIs for webmasters and editors to assign appropriate values.

Configure Universal Pixel Channel Info Mixin to Channels

Webmasters can configure channel-level default Universal Pixel data values through the Channel properties UI once the Universal Pixel ChannelInfo Mixin is configured for the channel:

The following parameters are available:

 Parameters  Type  Description  Required?  Default value
 Account ID  String  The account identifier (supplied by BloomReach)  Yes  
 Domain Key  String  The BloomReach­ provided ID of the domain receiving the request. This parameter identifies the specific site language version when one account ID hosts multiple site versions with different languages. BloomReach uses this parameter value to ensure that only query and analytics data that pertain to that language are used for respective features.  No  
 Default Universal Pixel Variables  Document Link  Link to a Universal Pixel Variables document in which webmasters can set channel-wide default Universal Pixel data values to be merged together if either a landing page or content-driven page doesn't override some Universal Pixel data values.  No  
 Enabled  Boolean  Whether Universal Pixel Scriptlets should be enabled in live pages.  No  True
 Disabled In Preview  Boolean  Whether Universal Pixel Scriptlets should be disabled in preview pages.  No  True

To configure the Universal Pixel ChannelInfo Mixin for a channel, set or add the value com.onehippo.cms7.addon.unipixel.site.channel.UniversalPixelChannelInfo to the hst:channelinfomixins property of the channel info configuration node as follows:

definitions:
  config:
    /hst:hst/hst:configurations/hippoaddonuniversalpixelintegrationdemo/hst:workspace/hst:channel:
      .meta:residual-child-node-category: content
      jcr:primaryType: hst:channel
      hst:name: Hippo Addon Universal Pixel Integration Support Demo Project
      hst:type: website
      hst:channelinfoclass: com.onehippo.cms7.demo.pixel.demo.channel.WebsiteInfo
      hst:channelinfomixins: [com.onehippo.cms7.addon.unipixel.site.channel.UniversalPixelChannelInfo]
      # ...

This causes the Experience manager to show the Universal Pixel Channel Properties panel as shown above.

If you have many channels in different environments, you might want to write a Groovy Updater script like the following example to automate adding com.onehippo.cms7.addon.unipixel.site.channel.UniversalPixelChannelInfo value to the hst:channelinfomixins property for each channel. As described in the JavaDoc comment below, this example script assumes that you execute the script against a JCR query parameter setting, for example /jcr:root/hst:hst/hst:configurations//hst:workspace/hst:channel for all the existing channels.

// configure_universal_pixel_channel_info_mixins.groovy
package org.hippoecm.frontend.plugins.cms.admin.updater

import javax.jcr.Node
import javax.jcr.RepositoryException
import javax.jcr.Session
import org.apache.commons.lang.ArrayUtils;
import org.hippoecm.repository.util.JcrUtils;
import org.onehippo.repository.update.BaseNodeUpdateVisitor

/**
 * Example Groovy Updater Script to configure Universal Pixel ChannelInfo Mixin types to each channel configuration node.
 * <p>
 * It is assumed that this updater is configured with a JCR query,
 * <code>/jcr:root/hst:hst/hst:configurations//hst:workspace/hst:channel</code>,
 * which searches and iterates each channel configuration node through JCR query execution.
 */
class ExampleConfigureUniversalPixelChannelInfoMixinsUpdaterVisitor extends BaseNodeUpdateVisitor {

  String upixelMixinChannelInfo = "com.onehippo.cms7.addon.unipixel.site.channel.UniversalPixelChannelInfo"

  boolean doUpdate(Node node) {
    log.debug "Visiting channel config node at ${node.path}"
    if (node.hasProperty("hst:channelinfoclass")) {
      String[] oldValues =
          JcrUtils.getMultipleStringProperty(node, "hst:channelinfomixins", ArrayUtils.EMPTY_STRING_ARRAY)
      if (!ArrayUtils.contains(oldValues, upixelMixinChannelInfo)) {
        node.setProperty("hst:channelinfomixins", ArrayUtils.add(oldValues, upixelMixinChannelInfo))
        return true
      }
    }
    return false
  }

  boolean undoUpdate(Node node) {
    throw new UnsupportedOperationException('Updater does not implement undoUpdate method')
  }
}

Configure Extra Custom Pixel Schema

By default, the Universal Pixel editor UIs only shows the predefined default BloomReach Universal Pixel variables, such as "Page type" and "Page labels".

If your site adds custom Universal Pixel variables, you need to provide JSON Schema resource(s) through the Universal Pixel addon configuration at /hippo:configuration/hippo:modules/universal-pixel/hippo:moduleconfig, like this:

definitions:
  config:
    /hippo:configuration/hippo:modules/universal-pixel/hippo:moduleconfig:
      custom.vars.source: jcr:/hippo:configuration/hippo:modules/universal-pixel/hippo:moduleconfig/custom.pixel.schema
      custom.pixel.schema:
        type: string
        resource: custom-pixel-schema.json​​​​​

The custom.vars.source property of the module configuration accepts a comma separated string for multiple custom JSON schema resource locations. Each resource location could be either a classpath: resource or a jcr: string property resource.

For example, if custom.vars.source property is set to classpath:/org/example/MySchema.json, jcr:/a/b/c/prop1, then the Universal Pixel Integration addon will load and merge both resources, one from the classpath (e.g, cms/WEB-INF/classes/org/example/MySchema.json) and the other from the JCR property /a/b/c/@prop1 of type string, with the default Unviersal Pixel variables.

In the above configuration example, it specifies the property value with a jcr: string property resource, located at /hippo:configuration/hippo:modules/universal-pixel/hippo:moduleconfig/custom.pixel.schema, i.e. located in the same node. A custom JSON schema resource could look like this:

{
    "title": "MyCommercePixelSchema",
    "type": "object",
    "properties": {
        "mycommercetags": {
            "title": "My commerce tags",
            "description": "My commerce tags",
            "type": "array",
            "format": "csv",
            "items": {
                "type": "string"
            }
        },
        "mycommercescore": {
            "title": "My commerce score",
            "description": "My commerce score",
            "type": "integer",
            "minimum": 1,
            "maximum": 10
        }
    },
    "required": [  ]
}

The Universal Pixel Integration addon will scan each custom JSON schema resource and iterate over their properties to (re)register additional custom Universal Pixel variables on startup or whenever the configuration is updated at runtime. In the above example, it registers two custom variables, "mycommercetags" and "mycommercescore", which are then shown to webmasters and editors in the editor UIs.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?