{"id":27069,"date":"2025-01-14T21:48:55","date_gmt":"2025-01-14T21:48:55","guid":{"rendered":"https:\/\/peraltafinancing.com\/analytics\/ga4-to-piwik-pro-using-server-side-google-tag-manager\/"},"modified":"2025-01-14T21:48:55","modified_gmt":"2025-01-14T21:48:55","slug":"ga4-to-piwik-pro-using-server-side-google-tag-manager","status":"publish","type":"post","link":"https:\/\/fivemor.com\/?p=27069","title":{"rendered":"GA4 to Piwik PRO Using Server-side Google Tag Manager"},"content":{"rendered":"


\n<\/p>\n

\n

There are two<\/strong> new custom templates<\/a> available in server-side Google Tag Manager<\/strong>. These templates have been designed to facilitate Piwik PRO<\/a> tracking in a server-side container.<\/p>\n

    \n
  1. Piwik PRO Client<\/strong> -> This Client<\/em> template interacts with the Piwik PRO JavaScript tracker<\/a> and lets you route Piwik PRO tracking through a server-side GTM container. GitHub repo<\/a>.<\/li>\n
  2. Piwik PRO<\/strong> -> The tag<\/em> template works in unison with the Piwik PRO Client, forwarding the hits to the Piwik PRO endpoint. GitHub repo<\/a>.<\/li>\n<\/ol>\n

    Read this article to learn more about how these templates work.<\/em><\/a><\/p>\n

    However, both templates have been built with a universal application in mind. The Client<\/strong> template produces event data that can be consumed by other vendors\u2019 tags, too. Similarly, the tag<\/strong> template has been designed so that it can work with other Clients.<\/p>\n

    In this article, I\u2019ll show you how to quite<\/em> easily take an incoming Google Analytics 4<\/strong> stream in server-side Google Tag Manager (claimed by the built-in GA4 Client) and map that to a format that can be utilized by the Piwik PRO tag.<\/p>\n

    \n

    <\/p>\n

    \"First<\/p>\n

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

    As the lousy illustration above shows, we\u2019ll use the GA4 Client<\/strong> to handle the incoming stream, but we\u2019ll then create a Piwik PRO tag<\/strong> to take the data generated by the GA4 Client and forward it to Piwik PRO servers (in the correct format, of course).<\/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

    Getting started<\/h2>\n

    To start with, we already have an established data stream for proxying Google Analytics 4 hits through a server-side Google Tag Manager container.<\/p>\n

    \n

    <\/p>\n

    \"SGTM<\/p>\n

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

    The property collects a variety of Google Analytics 4 data, but we\u2019re going to focus on the following four events in our mapping to Piwik PRO:<\/p>\n

      \n
    1. The page_view<\/code> event is sent whenever a page is loaded in the browser.<\/li>\n
    2. The view_item<\/code> event is sent whenever a product is viewed.<\/li>\n
    3. The add_to_cart<\/code> event is sent whenever a product is added to the cart.<\/li>\n
    4. The purchase<\/code> event is sent whenever a purchase is completed.<\/li>\n<\/ol>\n

      This is a very typical business-critical<\/em> event list. To keep things concise in this article, we\u2019ll focus on just these four and ignore the rest when building the mapping to Piwik PRO.<\/p>\n

      How the tag template works<\/h2>\n

      First of all, remember to read this article<\/a> for a more in-depth exploration of the new Piwik PRO templates.<\/p>\n

      To get started with the tag template, you need to fill in the Account Name<\/strong> and the Site or App ID<\/strong> fields. The values for these fields can be found in your Piwik PRO settings.<\/p>\n

      \n

      <\/p>\n

      \"Account<\/p>\n

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

      If you then scroll down the tag template, you\u2019ll find that almost all the fields have a default value of Inherit from Client<\/strong>.<\/p>\n

      This means that the field automatically grabs the value from what the server-side Client produced as long as it\u2019s in the correct format<\/em>.<\/p>\n

      The Piwik PRO Client has of course been built so that it generates the values correctly for the tag, but the GA4 Client<\/strong> understandably doesn\u2019t consider Piwik Pro\u2019s idiosyncracies in its output.<\/p>\n

      GA4 Event Data mapped to Piwik PRO parameters<\/h3>\n

      Here is the list of fields that the Piwik PRO tag template can read automatically<\/strong> from the GA4 Client:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
      GA4 Event Data key<\/th>\nMaps to Piwik PRO parameter<\/th>\nField name in the tag UI<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
      page_location<\/code><\/td>\nurl<\/code><\/td>\nEvent URL<\/td>\nThe URL of the page where the event happened.<\/td>\n<\/tr>\n
      page_referrer<\/code><\/td>\nurlref<\/code><\/td>\nReferrer URL<\/td>\nThe referrer of the page where the event happened.<\/td>\n<\/tr>\n
      user_id<\/code><\/td>\nuid<\/code><\/td>\nUser ID<\/td>\nUser ID for logged-in users.<\/td>\n<\/tr>\n
      ip_override<\/code><\/td>\ncip<\/code><\/td>\nOverride User IP<\/td>\nIP address of the visitor.<\/td>\n<\/tr>\n
      value<\/code><\/td>\nrevenue<\/code><\/td>\nRevenue<\/td>\nValue of the event (for e-commerce).<\/td>\n<\/tr>\n
      user_agent<\/code><\/td>\nua<\/code><\/td>\n–<\/td>\nUser-Agent string of the user\u2019s browser.<\/td>\n<\/tr>\n
      language<\/code><\/td>\nlang<\/code><\/td>\n–<\/td>\nBrowser language.<\/td>\n<\/tr>\n
      screen_resolution<\/code><\/td>\nres<\/code><\/td>\n–<\/td>\nScreen resolution of the visitor\u2019s browser.<\/td>\n<\/tr>\n
      client_id<\/code><\/td>\n_id<\/code><\/td>\nVisitor ID<\/td>\nThe tag automatically converts the GA4 Client ID to the correct Piwik PRO format (16-character hexadecimal hash).<\/td>\n<\/tr>\n
      page_title<\/code><\/td>\naction_name<\/code><\/td>\nEvent (Action) Name<\/td>\nWith page view hits, the page_title<\/code> is automatically used as action_name<\/code>.<\/td>\n<\/tr>\n
      transaction_id<\/code><\/td>\nec_id<\/code><\/td>\nOrder ID<\/td>\nThe ID of the transaction.<\/td>\n<\/tr>\n
      items<\/code><\/td>\nec_products<\/code><\/td>\nProducts<\/td>\nThe GA4 items<\/code> array is automatically converted to the correct ec_products<\/code> format.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

      These keys are accounted for by the GA4 Client and the Piwik PRO tag template, so you can leave them with the Inherit from Client<\/strong> option enabled.<\/p>\n

      The rest of the parameters that you need to map or generate depend on the event you are collecting. The full inventory of parameters supported by the Piwik PRO servers can be found in their HTTP API documentation<\/a>.<\/p>\n

      You can add the missing parameters by editing the Piwik PRO tag fields or by using a Transformation in SGTM<\/a>.<\/p>\n

      The \u201crec\u201d parameter<\/h3>\n

      The tag template sets the rec<\/code> parameter to 1<\/code> by default. This means that the request is recorded in your Piwik PRO instance.<\/p>\n

      If, for some reason, you don\u2019t<\/em> want the hit to be registered in Piwik PRO, you can set rec<\/code> to 0<\/code> using the Additional Parameters<\/strong> field in the tag UI. Any parameters you enter here will override any previous values registered by the tag.<\/p>\n

      \n

      <\/p>\n

      \"Additional<\/p>\n

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

      The \u201c_id\u201d parameter<\/h3>\n

      Piwik PRO uses a 16-character-long hexadecimal hash<\/strong> as the value of the Visitor ID. This is collected with the parameter _id<\/code>.<\/p>\n

      The tag template automatically uses the client_id<\/code> value stored in the Event Data object when creating the _id<\/code> value.<\/p>\n

      To collect the ID in the correct format, the Client ID is first hashed with the SHA256 algorithm and then the first 16 characters are used for the Visitor ID.<\/p>\n

      \n

      <\/p>\n

      \"GA4<\/p>\n

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

      Of course, you can use your own value for the Visitor ID, but remember that it must<\/strong> be in the correct format for Piwik PRO to accept it.<\/p>\n

      The page_view event<\/h2>\n

      We\u2019ll build the mapping event by event, starting with page_view<\/code>.<\/p>\n

      Create a new Piwik PRO tag in server-side Google Tag Manager, and set the Account Name<\/strong> and Site or App ID<\/strong> fields.<\/p>\n

      \n

      <\/p>\n

      \"Account<\/p>\n

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

      Next, under Event Configuration<\/strong>, choose Page \/ App View<\/strong> as the Event Type.<\/p>\n

      \n

      This is an optional step, because the tag template sees the page_view<\/code> event and deduces the event type from that. But sometimes the event name doesn\u2019t match the event type, so it\u2019s good to be explicit.<\/p>\n<\/blockquote>\n

      \n

      <\/p>\n

      \"Page<\/p>\n

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

      Finally, add a trigger to the tag. Focus on the page_view<\/code> event, and for good measure only fire the tag if the Client Name<\/strong> built-in variable is GA4<\/code>.<\/p>\n

      \n

      <\/p>\n

      \"Page<\/p>\n

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

      Finally, save the tag and go to Preview mode in server-side Google Tag Manager.<\/p>\n

      Preview and test<\/h3>\n

      The first thing we\u2019ll do is send a page_view<\/code> event to server-side Google Tag Manager, select it, and open the Console tab.<\/p>\n

      \n

      <\/p>\n

      \"Compiled<\/p>\n

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

      The Piwik PRO tag outputs this information into the console.<\/p>\n

      In the Compiled request body<\/strong>, you should see the action_name<\/code> with the page title. This is important, because this distinguishes the hit as a page view<\/strong> request.<\/p>\n

      Check also that you see the _id<\/code> parameter in the request. Copy the value of _id<\/code> to the clipboard.<\/p>\n

      Next, open the Tracker Debugger<\/a> in Piwik PRO. Filter the results for the Visitor ID you copied to the clipboard. This is what you should see:<\/p>\n

      \n

      <\/p>\n

      \"Tracker<\/p>\n

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

      Everything just \u2026 works! Your Page View hit has all the necessary data included.<\/p>\n

      You can click the little ><\/code> button next to the Page view<\/strong> event name to view more details about what was collected. The raw data should match what you saw in the Console tab of server-side Google Tag Manager.<\/p>\n

      And that\u2019s it<\/strong> for the page view event! It works! Here\u2019s a recap of what was done:<\/p>\n

        \n
      1. Create a new Piwik PRO tag.<\/li>\n
      2. Fill in the Account Name<\/em> and Site or App ID<\/em> fields correctly.<\/li>\n
      3. Trigger the tag on the page_view<\/code> event collected by the GA4 client.<\/li>\n<\/ol>\n

        Next, let\u2019s do the same for the three e-commerce events.<\/p>\n

        The product-detail-view event<\/h2>\n

        The GA4 analogy to Piwik PRO\u2019s product-detail-view<\/code> is the view_item<\/code> event.<\/p>\n

        Let\u2019s follow the same process as above to map this event correctly.<\/p>\n

        First, we\u2019ll create a new Piwik PRO tag with the Account Name<\/strong> and Site or App ID<\/strong> populated.<\/p>\n

        Now, let\u2019s choose Ecommerce<\/strong> as the Event Type.<\/p>\n

        \n

        <\/p>\n

        \"Ecommerce<\/p>\n

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

        When you choose this, a new section titled Ecommerce<\/strong> appears.<\/p>\n

        Here, the key field is Ecommerce Event Type<\/strong>. We\u2019ll keep that as Inherit from Client<\/strong>, but it won\u2019t work properly until we add the relevant field into the Event Data object using a Transformation. We\u2019ll get to this in a bit.<\/p>\n

        Create a Custom Event<\/strong> trigger with ^(view_item)$<\/code> as the value of the Event name<\/strong> field, and check Use regex matching<\/strong>. Add a condition to check for the GA4 Client, same as you did with the Page View tag.<\/p>\n

        Once ready, save the trigger and add it to the tag.<\/p>\n

        \n

        <\/p>\n

        \"Ecommerce<\/p>\n

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

        We\u2019re using a regex match for the event name, because we\u2019ll expand this trigger soon with other Ecommerce events.<\/p>\n

        Finally, save the tag.<\/p>\n

        The Event Type parameter<\/h3>\n

        The Event Type parameter in the Piwik PRO request is e_t<\/code>, and so the name of the field we need to add with a Transformation is x-pp-e_t<\/code> (remember that x-pp-<\/code> is the prefix for all Piwik PRO-specific parameters).<\/p>\n

        Piwik PRO accepts one of these as the value: order<\/code>, product-detail-view<\/code>, add-to-cart<\/code>, cart-update<\/code>, remove-from-cart<\/code>. In this article, we\u2019ll focus just on the first three.<\/p>\n

        To make things easier to manage, start by creating a new Lookup Table<\/strong> variable, where the Input variable is the built-in {{Event Name}}<\/code> variable. Add just one row, which maps view_item<\/code> in the input (the value of {{Event Name}}<\/code>) to product-detail-view<\/code> in the output:<\/p>\n

        \n

        <\/p>\n

        \"Event<\/p>\n

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

        Next, create a new Augment Event Transformation<\/strong> for Piwik PRO.<\/p>\n

        Go to Transformations<\/strong> in the container UI, and click to create a new Augment Event Transformation.<\/p>\n

        Here, add a new row with x-pp-e_t<\/code> as the Name. Set the Lookup Table variable you just created as the Value.<\/p>\n

        \n

        <\/p>\n

        \"Ecommerce<\/p>\n

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

        This Transformation populates the x-pp-e_t<\/code> field with the correct Ecommerce event name if<\/em> the event name is mapped in the Lookup Table.<\/p>\n

        Preview and test<\/h3>\n

        Once you\u2019ve created the tag and the trigger and you\u2019ve updated the Transformation, you can go into Preview mode and do whatever it takes to fire a standard view_item<\/code> event to your GA4 Client.<\/p>\n

        The Piwik PRO tag should fire with the view_item<\/code> event, and you should see something like this in the Console tab with the event selected:<\/p>\n

        \n

        <\/p>\n

        \"product-detail-view\"\/<\/p>\n

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

        When you open Tracker Debugger<\/strong> in Piwik PRO, you should see this:<\/p>\n

        \n

        <\/p>\n

        \"product<\/p>\n

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

        The tag template automatically<\/em> mapped the items<\/code> array that the GA4 Client produced into the correct format digested by the Piwik PRO tag (ec_products<\/code>).<\/p>\n

        Nice, product-detail-view<\/code> works now, too. Here\u2019s what we did:<\/p>\n

          \n
        1. Create a new Lookup Table that maps GA4 event names to their Piwik PRO counterparts.<\/li>\n
        2. Create a new the Augment Event Transformation with Event Type (x-pp-e_t<\/code>), derived from the built-in {{Event Name}}<\/code> variable using the Lookup Table.<\/li>\n
        3. Add a trigger to the tag that only fires it when an Ecommerce event occurs (view_item<\/code> in this case).<\/li>\n<\/ol>\n

          This is getting easier by the event!<\/p>\n

          Next, add-to-cart<\/code>.<\/p>\n

          The add-to-cart event<\/h2>\n

          Because we\u2019ve laid all the groundwork, getting the add-to-cart<\/code> event working is as easy as editing the Lookup Table variable for the x-pp-e_t<\/code> Transformation and modifying the trigger to also fire on the add_to_cart<\/code> event.<\/p>\n

          Here\u2019s what the modified Lookup Table variable looks like:<\/p>\n

          \n

          <\/p>\n

          \"add-to-cart<\/p>\n

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

          \n

          Please note that the Input<\/strong> has add_to_cart<\/code> with underscores (this is the event name as GA4 uses it) and the Output<\/strong> has add-to-cart<\/code> with hyphens (this is the Event Type for Piwik PRO).<\/p>\n<\/blockquote>\n

          Here\u2019s what the updated trigger should be \u2013\u00a0as you can see, the regular expression is now ^(view_item|add_to_cart)$<\/code>.<\/p>\n

          \n

          <\/p>\n

          \"Add<\/p>\n

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

          \n

          Again, make sure the trigger looks for the GA4 add_to_cart<\/code> event name and not the Piwik PRO add-to-cart<\/code>.<\/p>\n<\/blockquote>\n

          Save everything.<\/p>\n

          Preview and test<\/h3>\n

          This should be easy \u2013 go to Preview mode, send a GA4 add_to_cart<\/code> event to your Server container, and check the Console tab with the add_to_cart<\/code> event selected:<\/p>\n

          \n

          <\/p>\n

          \"Add<\/p>\n

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

          Wow, that looks good right away! The Tracker Debugger confirms our success:<\/p>\n

          \n

          <\/p>\n

          \"Tracker<\/p>\n

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

          Excellent, it\u2019s all good!<\/p>\n

          Here\u2019s what we did this time:<\/p>\n

            \n
          1. Modify the Lookup Table to process the mapping of add_to_cart<\/code> (GA4) to add-to-cart<\/code> (Piwik PRO).<\/li>\n
          2. Update the trigger to also fire with the add_to_cart<\/code> event.<\/li>\n<\/ol>\n

            The final event we\u2019ll cover in this article is order<\/code>.<\/p>\n

            The order event<\/h2>\n

            The order<\/code> event in Piwik PRO maps to the purchase<\/code> event of GA4.<\/p>\n

            Let\u2019s see if everything is as easy as in the previous section with add-to-cart<\/code>.<\/p>\n

            First, update the Lookup Table to account for the purchase<\/code> > order<\/code> mapping.<\/p>\n

            \n

            <\/p>\n

            \"Purchase<\/p>\n

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

            Then, update the trigger to listen for the purchase<\/code> event, too, by changing the regular expression to ^(view_item|add_to_cart|purchase)$<\/code>.<\/p>\n

            \n

            <\/p>\n

            \"Purchase<\/p>\n

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

            Finally, save everything.<\/p>\n

            Preview and test<\/h3>\n

            Refresh Preview mode, and do something to generate a purchase<\/code> event to your SGTM endpoint. This is what the Console tab should include:<\/p>\n

            \n

            <\/p>\n

            \"purchase<\/p>\n

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

            OK, ok! It looks good. The Event Type (order<\/code>) is there, we\u2019ve got revenue<\/code> (mapped from GA4\u2019s value<\/code> automatically), ec_id<\/code> is there with the Order ID, and ec_products<\/code> is populated as well. What about the Tracker Debugger<\/strong>?<\/p>\n

            \n

            <\/p>\n

            \"Order<\/p>\n

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

            It\u2019s good!<\/p>\n

            Thanks to the automatic mapping of transaction_id<\/code> to ec_id<\/code> and value<\/code> to revenue<\/code>, we didn\u2019t have to make any changes to the tag.<\/p>\n

            Summary<\/h2>\n

            In this article, we started with a GA4 data stream collecting the following events:<\/p>\n