Configure Universal Pixel Integration Addon

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:

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.