Install Universal Pixel Integration Addon

Warning: Universal Pixel Integration was an integration with Bloomreach Discovery. This addon is no longer maintained and has been removed from brXM 16.2 and later.

Overview

To install the Universal Pixel Integration Addon, you must add the required Maven dependencies, enable the Open UI Extension, and configure the shared library. This page provides step-by-step instructions for each task.

Add Maven Dependencies

Add the following dependencies to your content authoring application (cms-dependencies/pom.xml):

  <dependencies>
    <!-- SNIP -->

    <dependency>
      <groupId>com.onehippo.cms7</groupId>
      <artifactId>hippo-addon-universal-pixel-integration-repository</artifactId>
    </dependency>

    <dependency>
      <groupId>com.onehippo.cms7</groupId>
      <artifactId>hippo-addon-universal-pixel-integration-frontend</artifactId>
    </dependency>

    <dependency>
      <groupId>com.onehippo.cms7</groupId>
      <artifactId>hippo-addon-universal-pixel-integration-frontend-ng</artifactId>
    </dependency>
  </dependencies>

Add the following dependency to your content delivery application (site/components/pom.xml):

  <dependencies>
    <!-- SNIP -->

    <dependency>
      <groupId>com.onehippo.cms7</groupId>
      <artifactId>hippo-addon-universal-pixel-integration-hst</artifactId>
    </dependency>
  </dependencies>

Configure the Shared Library

The Universal Pixel Integration addon provides a shared library used by both the content authoring (CMS) and content delivery applications. To make this library available, configure the dependency in both the cargo.run Maven profile and the distribution assembly XML file.

In your project's root pom.xml, update the cargo.run Maven profile to include the hippo-addon-universal-pixel-integration-api JAR as a shared module:

    <!-- SNIP -->

    <profile>
      <id>cargo.run</id>
      <dependencies>
        <!-- SNIP -->
        <dependency>
          <groupId>com.onehippo.cms7</groupId>
          <artifactId>hippo-addon-universal-pixel-integration-api</artifactId>
          <scope>provided</scope>
        </dependency>
        <!-- SNIP -->
      </dependencies>
      <!-- SNIP -->
      <build>
        <plugins>
          <plugin>
            <groupId>org.codehaus.cargo</groupId>
            <artifactId>cargo-maven3-plugin</artifactId>
            <configuration>
              <!-- SNIP -->
              <container>
                <!-- SNIP -->
                <dependencies>
                  <!-- SNIP -->
                  <dependency>
                    <groupId>com.onehippo.cms7</groupId>
                    <artifactId>hippo-addon-universal-pixel-integration-api</artifactId>
                    <classpath>shared</classpath>
                  </dependency>
                  <!-- SNIP -->
                </dependencies>
              </container>
            </configuration>
          </plugin>
          <!-- SNIP -->
        </plugins>
      </build>
    </profile>

    <!-- SNIP -->

This configuration ensures that the Apache Tomcat container started by the cargo.run profile includes the hippo-addon-universal-pixel-integration-api JAR on the shared classpath.

When building a tar.gz distribution file using the dist Maven profile, define shared dependencies in the Maven Assembly Plugin descriptor file (src/main/assembly/shared-lib-component.xml). Update the file as shown:

<component xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/component/1.1.2"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/component/1.1.2
                               http://maven.apache.org/xsd/component-1.1.2.xsd">
  <dependencySets>
    <dependencySet>
      <useProjectArtifact>false</useProjectArtifact>
      <outputDirectory>shared/lib</outputDirectory>
      <scope>provided</scope>
      <includes>
        <!-- SNIP -->
        <include>com.onehippo.cms7:hippo-addon-universal-pixel-integration-api</include>
      </includes>
    </dependencySet>
  </dependencySets>
</component>

Also, add the hippo-addon-universal-pixel-integration-api dependency to the dist Maven profile in your project's root pom.xml:

<profile>
  <id>dist</id>
  <dependencies>
    <!-- SNIP -->
    <dependency>
      <groupId>com.onehippo.cms7</groupId>
      <artifactId>hippo-addon-universal-pixel-integration-api</artifactId>
      <scope>provided</scope>
    </dependency>
  </dependencies>
  <build>
    <!-- SNIP -->
  </build>
</profile>

After these changes, the distribution tar.gz file will include the hippo-addon-universal-pixel-integration-api JAR in the shared library path.

Enable WicketSessionFilter for JAX-RS Services

The Universal Pixel Integration addon provides a REST endpoint used by the Universal Pixel Editor UI. To allow this endpoint to access data using the current CMS user's session, configure the WicketSessionFilter in the CMS application's web.xml (cms/src/main/webapp/WEB-INF/web.xml):

  <filter>
    <filter-name>UniversalPixelJaxrsWicketSessionFilter</filter-name>
    <filter-class>org.apache.wicket.protocol.http.servlet.WicketSessionFilter</filter-class>
    <init-param>
      <param-name>filterName</param-name>
      <param-value>CMS</param-value>
    </init-param>
  </filter>

  <filter-mapping>
    <filter-name>UniversalPixelJaxrsWicketSessionFilter</filter-name>
    <url-pattern>/ws/universal-pixel/*</url-pattern>
  </filter-mapping>

Configure Authorization for JAX-RS Services

The Universal Pixel Integration Addon JAX-RS endpoint requires users to have the hippo:rest permission on the module path /hippo:configuration/hippo:modules/universal-pixel. For details on configuring permissions, see Repository JAX-RS Service.

To grant a specific group permission to manage Universal Pixel variables, add the hippo:rest privilege to the group's role. For example:

/hippo:configuration/hippo:roles/editor:
  jcr:primaryType: hipposys:role
  hipposys:privileges: ['hippo:editor', 'hippo:rest']
  hipposys:roles: [author]
  hipposys:system: true

For more information on authorization, see Repository Authorization and Permissions.

Additional Instructions for Versions 14.6 and Earlier

If your project uses brXM 14.6 or earlier, you must also define the version property and dependency management entries in the root pom.xml:

  <properties>
    <!-- align pixel version with brXM version -->
    <hippo-addon-universal-pixel-integration.version>${essentials.version}</hippo-addon-universal-pixel-integration.version>
  </properties>

  <!-- SNIP -->

  <dependencyManagement>
    <dependencies>
      <!-- SNIP -->

      <dependency>
        <groupId>com.onehippo.cms7</groupId>
        <artifactId>hippo-addon-universal-pixel-integration-api</artifactId>
        <version>${hippo-addon-universal-pixel-integration.version}</version>
        <scope>provided</scope>
      </dependency>

      <dependency>
        <groupId>com.onehippo.cms7</groupId>
        <artifactId>hippo-addon-universal-pixel-integration-repository</artifactId>
        <version>${hippo-addon-universal-pixel-integration.version}</version>
      </dependency>

      <dependency>
        <groupId>com.onehippo.cms7</groupId>
        <artifactId>hippo-addon-universal-pixel-integration-frontend</artifactId>
        <version>${hippo-addon-universal-pixel-integration.version}</version>
      </dependency>

      <dependency>
        <groupId>com.onehippo.cms7</groupId>
        <artifactId>hippo-addon-universal-pixel-integration-frontend-ng</artifactId>
        <version>${hippo-addon-universal-pixel-integration.version}</version>
      </dependency>

      <dependency>
        <groupId>com.onehippo.cms7</groupId>
        <artifactId>hippo-addon-universal-pixel-integration-hst</artifactId>
        <version>${hippo-addon-universal-pixel-integration.version}</version>
      </dependency>
    </dependencies>
  </dependencyManagement>

Starting with version 14.7.0, these properties and dependencies are included in the enterprise release POM and do not need to be defined in implementation projects.