Install Universal Pixel Integration Addon

Introduction

Installing the Universal Pixel Integration Addon requires adding Maven dependencies, enabling the Open UI Extension, and configuring the shared library. Each step is described in this page.

Add Dependencies

Add the following dependencies to the 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>

And, add the following dependency to the 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 Shared Library

The Universal Pixel Integration addon provides a shared library for both content authoring (CMS) and content delivery web applications. In order to make that shared library available, configure the shared library dependency in both the cargo.run Maven profile and the distribution assembly XML file.

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

    <!-- 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 -->

Now, the Apache Tomcat container started by the cargo.run profile makes the hippo-addon-universal-pixel-integration-api JAR module available on the shared classpath.

Also, when creating a tar.gz distribution file through the dist Maven profile, shared dependencies are defined in a Maven Assembly Plugin descriptor file, i.e. src/main/assembly/shared-lib-component.xml. Update it as follows:

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

Be sure to add the hippo-addon-universal-pixel-integration-api dependency in the dist Maven profile in your project's root pom.xml so that it can recognize the dependency during the assembly process.

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

Now, the distribution tar.gz file will contain the hippo-addon-universal-pixel-integration-api JAR module in the shared library path.

Enabling WicketSessionFilter for Universal Pixel Integration Addon JAX-RS Services

The Universal Pixel Integration addon includes a REST endpoint used by the Universal Pixel Editor UI. To enable the REST endpoint to access data through the current CMS user's session, configure WicketSessionFilter by adding the servlet filter configuration in the web.xml file of the CMS application (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 Universal Pixel Integration Addon JAX-RS Services

The Universal Pixel Integration Addon JAX-RS endpoint is authorized to the users who have the hippo:rest permission on the module path, /hippo:configuration/hippo:modules/universal-pixel, following the best practices described in Repository JAX-RS Service. Therefore, if the current CMS user doesn't have the permission, the user won't be able to view or edit Universal Pixel variables.

As one of the simplest ways to allow users in a specific group to manage the Universal Pixel variables, you can add "hippo:rest" permission to the group like the following example:

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

For more detail on authorization configuration, see Repository Authorization and Permissions.

Additional Instructions for versions 14.6 and older

If your implementation project is running Bloomreach Experience Manager 14.6 or earlier, also add the version property and dependency definitions in the dependency management section 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>

As of version 14.7.0, the above property and dependencies are provided by the enterprise release POM and don't need to be explicitly defined in implementation projects anymore.