{"id":29712,"date":"2025-01-15T22:24:56","date_gmt":"2025-01-15T22:24:56","guid":{"rendered":"https:\/\/peraltafinancing.com\/analytics\/new-piwik-pro-templates-in-server-side-google-tag-manager\/"},"modified":"2025-01-15T22:24:56","modified_gmt":"2025-01-15T22:24:56","slug":"new-piwik-pro-templates-in-server-side-google-tag-manager","status":"publish","type":"post","link":"https:\/\/fivemor.com\/?p=29712","title":{"rendered":"New Piwik PRO Templates In Server-side Google Tag Manager"},"content":{"rendered":"


\n<\/p>\n

\n

Piwik PRO<\/a> has two<\/strong> new server-side Google Tag Manager<\/a> templates, and this article explains what they are and how they work.<\/p>\n

The first template, Piwik PRO Client<\/strong><\/a>, is designed to work in unison with the Piwik PRO HTTP API<\/a>. Most often these requests are generated by the Piwik PRO JavaScript tracker, but theoretically any<\/em> HTTP source that uses the same schema can send requests for the Client to claim. Once the Client claims the request, it generates an event data object<\/strong> that can be consumed by tags in the server-side Google Tag Manager container.<\/p>\n

The second template, Piwik PRO<\/strong><\/a>, is a tag template that takes the event data object<\/em>, compiles it into the format required by the Piwik PRO HTTP API<\/a>, and then dispatches it to the Piwik PRO instance.<\/p>\n

These two templates enable (at least) these two approaches:<\/p>\n

    \n
  1. Use some other vendor\u2019s tracker, such as Google Tag<\/strong> in the browser. Forward the hits to server-side Google Tag Manager. Claim the requests with the vendor\u2019s own Client (such as the GA4 Client), and use this data to fire the vendor\u2019s own tag as well as<\/em> the Piwik PRO tag.<\/li>\n<\/ol>\n
    \n

    <\/p>\n

    \"First<\/p>\n

    <\/a><\/p>\n<\/div>\n

      \n
    1. Use the Piwik PRO JavaScript tracker<\/strong> in the browser. Forward the hits to server-side Google Tag Manager. Claim the requests with the Piwik PRO Client<\/strong>, and use this data to fire the Piwik PRO tag and other vendors\u2019 tags, too, such as those designed for Google Ads<\/strong> and Meta Conversions API<\/strong>.<\/li>\n<\/ol>\n
      \n

      <\/p>\n

      \"Piwik<\/p>\n

      <\/a><\/p>\n<\/div>\n

      If you\u2019re curious about the first approach, check out this article I\u2019ve written about mapping Google Analytics 4 data to Piwik PRO<\/a> using the new Piwik PRO tag template.<\/p>\n


      \n X<\/span><\/p>\n

      \n
      \n The Simmer Newsletter<\/strong>\n <\/p>\n

      \n Subscribe to the Simmer newsletter<\/a> to get the latest news and content from Simo Ahava into your email inbox!\n <\/p>\n

      <\/span><\/p>\n

      The Client template<\/h2>\n
      \n

      <\/p>\n

      \"Piwik<\/p>\n

      <\/a><\/p>\n<\/div>\n

      The Piwik PRO Client<\/strong> template has been designed to capture requests that originate in Piwik PRO\u2019s client-side libraries.<\/p>\n

      For example, with the JavaScript API<\/a>, you can use a command like this to route all subsequent events by the tracker to your server-side Google Tag Manager endpoint:<\/p>\n

      \n
      _paq.push([\"setTrackerUrl\"<\/span>, \"https:\/\/sgtm.my-website.com\/ppms.php\"<\/span>]);\n<\/code><\/pre>\n<\/div>\n
      If you\u2019re using the Piwik PRO Analytics template<\/a> for client-side<\/strong> Google Tag Manager, you can use the Use a custom tracker URL<\/strong> setting to achieve the same easily:<\/p>\n
      \n
          <\/p>\n
          \"Custom<\/p>\n
          <\/a><\/p>\n<\/div>\n
      When a request comes in for the \/ppms.php<\/code> resource, the Piwik PRO Client (in server-side Google Tag Manager) claims<\/strong> the request and proceeds to generate an event data object<\/strong> with both common<\/em> event data keys as well as Piwik PRO-specific items.<\/p>\n
      How to install the template<\/h3>\n
      Because Google Tag Manager\u2019s Community Template Gallery<\/a> doesn\u2019t support distributing Client templates, you need to install the template manually.<\/p>\n
      First, navigate to the template.tpl<\/code> file in the GitHub repo<\/a> for the Client by following this link<\/a>. Download the file to your device.<\/p>\n
      Then, in your server-side Google Tag Manager container, browse to Templates<\/strong> and create a new Client<\/strong> template.<\/p>\n
      \n
          <\/p>\n
          \"Create<\/p>\n
          <\/a><\/p>\n<\/div>\n
      Once the editor opens, click the overflow menu in the top-right corner and choose Import<\/strong>.<\/p>\n
      \n
          <\/p>\n
          \"Import<\/p>\n
          <\/a><\/p>\n<\/div>\n
      Locate the template.tpl<\/code> file on your device, and select it to import it.<\/p>\n
      You should see the template load in the editor. Click Save<\/strong> to save the template.<\/p>\n
      Once the template is saved, head on over to Clients<\/strong> in the container, and click to create a new Client.<\/p>\n
      \n
          <\/p>\n
          \"Create<\/p>\n
          <\/a><\/p>\n<\/div>\n
      Select the Piwik PRO Client<\/strong> from the list of available templates.<\/p>\n
      How to configure the Client template<\/h3>\n
      The Client template has only a few configuration options. It\u2019s designed to work automatically<\/strong> whenever Piwik PRO JavaScript requests are dispatched to the server-side Google Tag Manager container.<\/p>\n
      The only manually configurable option is labeled Serve requests for ppms.js<\/strong>.<\/p>\n
      \n
          <\/p>\n
          \"Serve<\/p>\n
          <\/a><\/p>\n<\/div>\n
      Checking this option enables first-party serving<\/strong> of the Piwik PRO JavaScript library.<\/p>\n
      \n
      This means that instead of loading the JavaScript from Piwik PRO\u2019s own content distribution network, you load the library from the server-side Google Tag Manager domain. You need to configure your client-side Piwik PRO installation<\/a> to load the ppms.js<\/code> file from your own domain.<\/p>\n<\/blockquote>\n
      When you enable this option, you need to provide the Account name<\/strong> of your Piwik PRO environment. You also need to list all the allowed URL origins<\/strong> from which requests for the ppms.js<\/code> file are considered. Add the list of origins as a comma-separated string:<\/p>\n
      https:\/\/www.my-website.com,https:\/\/www.my-website.de,https:\/\/store.my-other-website.com<\/code><\/p>\n
      Check Cache the resource in server-side GTM<\/strong> to reduce network egress costs<\/em> by storing the file (temporarily) in the server cache.<\/p>\n
      Once you save the Client and publish (or preview) the container, the Client is active and ready to intercept incoming requests.<\/p>\n
      How the Client works<\/h3>\n
      The Client parses the incoming request from the web browser and creates an event data object<\/strong> with it.<\/p>\n
      \n
          <\/p>\n
          \"Event<\/p>\n
          <\/a><\/p>\n<\/div>\n
      In server-side Google Tag Manager, the only way that tags<\/strong> can fire is if a Client generates an event data object. This object typically contains common event data<\/a> as well as vendor-specific keys.<\/p>\n
      The Piwik PRO Client generates these common event data<\/strong> keys:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
      Event data key<\/th>\nPiwik PRO request parameter<\/th>\nDescription<\/th>\n\n<\/tr>\n<\/thead>\n
      event_name<\/code><\/td>\nN\/A<\/td>\nThe request event type. This is not always applicable to Piwik PRO requests.<\/td>\n\n<\/tr>\n
      client_id<\/code><\/td>\n_id<\/code><\/td>\nThe Visitor ID.<\/td>\n\n<\/tr>\n
      ip_override<\/code><\/td>\ncip<\/code><\/td>\nThe IP address of the visitor.<\/td>\n\n<\/tr>\n
      language<\/code><\/td>\nlang<\/code><\/td>\nThe browser language string.<\/td>\n\n<\/tr>\n
      page_location<\/code><\/td>\nurl<\/code><\/td>\nThe URL of the page the request was sent from.<\/td>\n\n<\/tr>\n
      page_path<\/code><\/td>\nN\/A<\/td>\nThe URL path of the page the request was sent from.<\/td>\n\n<\/tr>\n
      page_referrer<\/code><\/td>\nurlref<\/code><\/td>\nThe referrer URL of the page the request was sent from.<\/td>\n\n<\/tr>\n
      screen_resolution<\/code><\/td>\nres<\/code><\/td>\nThe screen resolution of the visitor\u2019s device.<\/td>\n\n<\/tr>\n
      ua<\/code><\/td>\nua<\/code><\/td>\nThe User-Agent string of the web browser.<\/td>\n\n<\/tr>\n
      user_id<\/code><\/td>\nuid<\/code><\/td>\nThe login ID of the visitor.<\/td>\n\n<\/tr>\n
      value<\/code><\/td>\nrevenue<\/code><\/td>\nThe revenue of the order.<\/td>\n\n<\/tr>\n
      value<\/code><\/td>\ne_v<\/code><\/td>\nThe event value.<\/td>\n\n<\/tr>\n<\/tbody>\n<\/table>\n
      Any parameter that isn\u2019t listed here but is part of the incoming request is added to the event data object using the parameter name with the prefix x-pp-<\/code>:<\/p>\n
      \n
          <\/p>\n
          \"x-pp-parameters\"\/<\/p>\n
          <\/a><\/p>\n<\/div>\n
      For more details about these Piwik PRO-specific parameters, consult the HTTP API documentation<\/a>.<\/p>\n
      This event data can then be used to trigger supported tags, allowing you to orchestrate a complete data pipeline using the Piwik PRO JavaScript tracker as the starting point.<\/p>\n
      The tag template<\/h2>\n
      The purpose of a Client<\/strong> in server-side Google Tag Manager is to claim<\/strong> an incoming HTTP request and (ideally) generate an event data object<\/strong> to trigger tags and populate them with data.<\/p>\n
      Tags, on the other hand, are typically request-agnostic<\/em>, which means that they should<\/em> be configurable to work with the event data object generated by any<\/strong> Client.<\/p>\n
      The Piwik PRO tag template<\/strong> has been designed to be as request-agnostic as possible, but it works best when coupled with a Piwik PRO Client.<\/p>\n
      How to install the tag template<\/h3>\n
      The easiest way to install the tag template is to browse to Templates<\/strong> in the server-side Google Tag Manager container, and then click Search Gallery<\/strong> in the Tag Templates section.<\/p>\n
      \n
          <\/p>\n
          \"Search<\/p>\n
          <\/a><\/p>\n<\/div>\n
      Here, you can search for piwik pro<\/code>.<\/p>\n
      \n
          <\/p>\n
          \"Piwik<\/p>\n
          <\/a><\/p>\n<\/div>\n
      \n
      Note!<\/strong> This is the official<\/strong> template by Piwik PRO. You might find other templates, too, but they have not been created by the Piwik PRO team. For most reliable results, I recommend you stick with the official templates.<\/p>\n<\/blockquote>\n
      Once you locate the template, install it after reading and approving any prompts it throws your way.<\/p>\n
      You can also install the tag template manually<\/strong> by first downloading the template.tpl file from Piwik PRO\u2019s GitHub repo<\/a>, and then following the same steps<\/a> as for the Client template.<\/p>\n
      Once you\u2019ve installed it, browse to Tags<\/strong> in the server-side Google Tag Manager container, and click New<\/strong> to create a new tag. Choose the Piwik PRO<\/strong> template.<\/p>\n
      \n
          <\/p>\n
          \"Piwik<\/p>\n
          <\/a><\/p>\n<\/div>\n
      Before we explore the template, let\u2019s walk through how the tag actually works.<\/p>\n
      How the tag template works<\/h3>\n
      The purpose of the tag template is to compile an HTTP request to your Piwik PRO instance using the Piwik PRO HTTP API<\/a>.<\/p>\n
      Minimally, you need to enter your Account name<\/strong> (myinstance.piwik.pro<\/code>) and your Site or App ID<\/strong><\/a>.<\/p>\n
      You\u2019ll also need to add a trigger<\/em> to the tag.<\/p>\n
      \n
      If the tag is orchestrated to work with a specific Client, such as the Piwik PRO Client or the GA4 Client, it\u2019s a good practice<\/strong> to modify the trigger so that it only fires the tag when this Client has claimed the request, like this:<\/p>\n<\/blockquote>\n
      \n
          <\/p>\n
          \"Piwik<\/p>\n
          <\/a><\/p>\n<\/div>\n
      As for populating the necessary parameters for the outgoing request, you have three<\/strong> options with the tag template:<\/p>\n
        \n
      1. Select Inherit from Client<\/strong> means that the field tries to grab the value directly from the event data object<\/strong> generated by the Client (more on this below<\/a>).<\/li>\n
      2. Add or select a value by editing the tag field (you can use variables).<\/li>\n
      3. Add any supported HTTP API parameter name and value to the Additional Parameters<\/strong> table in the tag (more on this below<\/a>, too).<\/li>\n<\/ol>\n
        Once the tag fires, it parses all the available fields and the values within to generate the outgoing request to your Piwik PRO instance.<\/p>\n
        It will transparently forward the data generated by the Piwik PRO Client to your Piwik PRO instance.<\/p>\n
        Integration with the Piwik PRO Client<\/h3>\n
        If you are using the Piwik PRO JavaScript tracker or the Piwik PRO HTTP API to collect hits to server-side Google Tag Manager, you can get by with a minimal<\/strong> setup in server-side Google Tag Manager.<\/p>\n
        This is because the Piwik PRO Client transparently forwards everything in the incoming request stream to the event data object, where the Piwik PRO tag then picks it up and sends to Piwik PRO servers.<\/p>\n
        In this case, the Piwik PRO tag could look as simple as this:<\/p>\n
        \n
            <\/p>\n
            \"Piwik<\/p>\n
            <\/a><\/p>\n<\/div>\n
        The tag only has Account Name<\/strong> and Site or App ID<\/strong> populated, and it fires on a trigger for all events generated when {{Client Name}}<\/code> equals<\/em> Piwik PRO Client<\/code>.<\/p>\n
        \u201cInherit from Client\u201d<\/h3>\n
        When you select Inherit from Client<\/strong> as the value of a tag field, the tag template looks at the event data object<\/strong> for the value relevant to that particular field.<\/p>\n
        \n
        Note that the fields in the tag are the most frequently used configurations. They don\u2019t cover every single possible aspect of a Piwik PRO data stream. The template sources other parameters too, when necessary, and you can always use Transformations<\/a> and Additional Parameters<\/a> to further configure the tracking.<\/p>\n<\/blockquote>\n
        Here are the tag fields with the associated event data logic included.<\/p>\n
        \n
        Remember that Piwik PRO-specific keys are prefixed with x-pp-<\/code>, and the rest of the key name comes from the HTTP API<\/a> parameter name.<\/p>\n<\/blockquote>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
        Field name in the tag UI<\/th>\nEvent data key<\/th>\n<\/tr>\n<\/thead>\n
        Anonymous Tracking<\/td>\nx-pp-uia<\/code> and x-pp-rmip<\/code><\/td>\n<\/tr>\n
        Event URL<\/td>\npage_location<\/code><\/td>\n<\/tr>\n
        Referrer URL<\/td>\npage_referrer<\/code><\/td>\n<\/tr>\n
        Event (Action) Name<\/td>\nx-pp-action_name<\/code> or page_title<\/code><\/td>\n<\/tr>\n
        Search Query<\/td>\nx-pp-search<\/code><\/td>\n<\/tr>\n
        Search Categories<\/td>\nx-pp-search_cats<\/code><\/td>\n<\/tr>\n
        Search Results Count<\/td>\nx-pp-search_count<\/code><\/td>\n<\/tr>\n
        External Link URL<\/td>\nx-pp-link<\/code><\/td>\n<\/tr>\n
        File Download URL<\/td>\nx-pp-download<\/code><\/td>\n<\/tr>\n
        Custom Event Category<\/td>\nx-pp-e_c<\/code><\/td>\n<\/tr>\n
        Custom Event Action<\/td>\nx-pp-e_a<\/code><\/td>\n<\/tr>\n
        Custom Event Name<\/td>\nx-pp-e_n<\/code><\/td>\n<\/tr>\n
        Custom Event Value<\/td>\nx-pp-e_v<\/code><\/td>\n<\/tr>\n
        Ecommerce Event Type<\/td>\nx-pp-e_t<\/code><\/td>\n<\/tr>\n
        Order ID<\/td>\nx-pp-ec_id<\/code> or transaction_id<\/code><\/td>\n<\/tr>\n
        Revenue<\/td>\nvalue<\/code><\/td>\n<\/tr>\n
        Sub-total<\/td>\nx-pp-ec_st<\/code><\/td>\n<\/tr>\n
        Shipping<\/td>\nx-pp-ec_sh<\/code><\/td>\n<\/tr>\n
        Tax<\/td>\nx-pp-ec_tx<\/code><\/td>\n<\/tr>\n
        Discount<\/td>\nx-pp-ec_dt<\/code><\/td>\n<\/tr>\n
        Products<\/td>\nx-pp-ec_products<\/code> or items<\/code><\/td>\n<\/tr>\n
        Visitor ID<\/td>\nclient_id<\/code><\/td>\n<\/tr>\n
        User ID<\/td>\nuser_id<\/code><\/td>\n<\/tr>\n
        Override User IP<\/td>\nip_override<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
        \n
        If there is an items<\/code> key in the event data object that is in the GA4 format<\/a>, then it is automatically<\/strong> transformed to the format that Piwik PRO requires ec_products<\/code> to be in.<\/p>\n<\/blockquote>\n
        Additionally, the Tag automatically inherits these fields from the event data object:<\/p>\n