If you are using Google Tag Manager to insert your Google Analytics tracking snippet, do not include your Google Analytics Measurement ID in the FastSpring App. This could result in the double-counting of events and sales.

This documentation provides implementation instructions and reference materials focused on how to implement Google Analytics 4 (GA4) inside of Google Tag Manager (GTM) and using the FastSpring GA events. GA4 is an analytics service that enables you to measure traffic and engagement across your websites and apps.

For more information about the migration from Universal Analytics to GA4 see Make the switch to Google Analytics 4.

Google Tag Manager can be used together with Google Analytics but is a separate tool. You can use Google Tag Manager to inject Google Analytics tracking scripts, but the two can also be used completely separately.

You may need to periodically update your Google Tag Manager settings to remain compliant with evolving browser standards and best practices.

Prerequisites

• Create your Google Tag Manager account and obtain your Google Tag Manager Container ID.
• Create your GA4 property and obtain your MEASUREMENT ID. You can follow instructions about it here.
• Do not set up Google Analytics integration in the FastSpring App or configure cross-domain tracking using plain code in the SBL integration.

Integration for all Checkouts

To set up Google Tag Manager integration for all checkouts:

1. In the FastSpring App, navigate to Developer Tools > Extensions > Google Tag Manager.
2. Click Setup.
3. Enter your Google Tag Manager Container ID and click Enable.

Custom Integration for Individual Checkouts

Only configure custom Google Tag Manager integration for individual Checkouts if you need to use different IDs for different Checkouts. Otherwise, configure Google Tag Manager integration for all Checkouts following the steps above.

1. In the FastSpring App, navigate to the Checkout you want to modify and click Settings.
2. Within the Checkout Settings, click Analytics Integration in the left menu.
3. In the Google Tag Manager Integration Behavior drop-down, select Use custom Google Tag Manager container ID for this checkout.
4. Enter your Google Analytics Tracking ID in the Google Tag Manager > Google Tag Manager custom container ID for this checkout field and click Save at the top right-hand corner of the page.

Set up Variables in GTM

FastSpring adds some variables to the data layer that can be used inside tags or triggers. Follow the steps below to add these as variables inside the Tag Manager dashboard.

1. Enter fsc-url as the Variable name.
2. Choose Data Layer Variable as the Variable Type.
3. Type fsc-url as the Data Layer Variable Name and choose Data Layer Version 2.
4. Click Save.
5. Repeat the steps above for the following variables:
   • fsc-url
   • fsc-referrer
   • fsc-eventAction
   • fsc-eventCategory
   • fsc-eventLabel
   • fsc-eventValue
   • fsc-currency
   • fsc-order-id – Contains the FastSpring order reference ID
   • fsc-order-tax – Contains the tax amount for this order
   • fsc-order-total – Contains the order total
   • fsc-coupon – Contains order coupon
6. Create the variable ga4-tracking-id with Constant as the Variable Type.
7. In the value field for ga4-tracking-id put your GA4 measurement ID.

For more information refer to the Google help page for user defined variables.

Installing GA4 using GTM

If you want to configure Google Analytics 4 inside Google Tag Manager apply the following instructions:

Cross-Domain Tracking for Popup and Embedded Checkouts

Cross-domain measurement in GA4 is a Google Analytics feature that allows you to see sessions from two related sites (such as your site and the FastSpring app) as a single session, rather than as two separate ones. This is sometimes called “site linking,” and it allows you to more effectively measure the entire customer journey. When using Store Builder Library, Popup Checkout, or Embedded Checkout on your site include the following attribute in the script that loads the FastSpring library: data-decorate-callback="decorateURL"

Example of loading the FastSpring library with the data-decorate attribute included:

<script id="fsc-api"
src="https://d1f8f9xcsvx3ha.cloudfront.net/sbl/0.9.2/fastspring-builder.min.js"
type="text/javascript" data-checkout="yourexamplestore.onfastspring.com/popup-yourexamplestore"
data-decorate-callback="decorateURL">
</script>

Copy and paste the following code into your page:

function decorateURL(url) {
  if (window.clsid) {
    var _pl = '&clientId=' + window.clsid.client_id
      + '&sessionId=' + window.clsid.session_id;
    return url + '?' + _pl;
  }
  return url;
}

Configure your domains in Google Analytics

This step is required only for Web Checkouts. Enable the cross-domain measurement and further define which links on your site do not trigger Outbound Click events when using enhanced measurement.

1. Open your Google Analytics account. Go to the Admin menu.
2. Choose the GA4 property that you want to modify. Then select Data Streams.
3. Choose the data stream to modify.
4. Under the Google tag section, select Configure tag settings.
5. Under the Settings section choose Configure your domains.
6. In the form add a new row with the following data (as the following image):
   a. Match type: Contains
   b. Domain: onfastspring.com

7. Repeat the previous steps to also include the paypal.com domain.

Tag Manager GA4 tag creation

Web Checkouts

This step is required for web Checkouts.

Follow these steps to create the Google Analytics GA4 Configuration Tag using a Google Analytics: GA4 Configuration tag type:

1. Click Tags > New.
2. Enter Google Analytics GA4 Configuration as the tag name.
3. Under Tag type, select Google Tag from the option list.
4. In the Tag ID field, enter {{ga4-tracking-id}}.
5. Click within the Triggering area and select New trigger (the plus sign in the top right corner).
6. Next, carry out these steps in the Configuration settings section:
   1. Under Configuration Parameter, add a new row with the following:
      1. Field name: cookie_flags
      2. Value: max-age=2592000;secure;samesite=none
   2. Add another row with the following:
      1. Field name: send_page_view
      2. Value: true
   3. Under Consent Settings, select No additional consent required.
7. Click within the Trigger configuration area, then click Triggers.
8. In the Choose a Trigger panel, choose Initialization - All Pages.
9. Click Save > Save.

Popup Checkout or Embedded Checkout

This step is required for Embedded and Popup Checkouts. Create the Google Analytics GA4 Configuration Tag using a Custom HTML tag type:

1. Inside Google Tag Manager, go to the Tags left menu and click the New button.
2. Choose the tag type Custom HTML.
3. Click Triggers; in the Choose a Trigger panel choose Initialization – All pages.
4. In the HTML field paste the following code:

<script async src="https://www.googletagmanager.com/gtag/js?id={{ga4-tracking-id}}"></script>
<script>
function gtag() {
  dataLayer.push(arguments);
}
gtag('js', new Date());
if (!window.clsid) {
  gtag('config', '{{ga4-tracking-id}}', {
    'cookie_flags': 'SameSite=None;Secure',
    'page_referrer': '{{fsc-referrer}}',
    'page_location': '{{fsc-url}}',
  });
  window.clsid = {
    client_id: '',
    session_id: ''
  };
  gtag('get', '{{ga4-tracking-id}}', 'client_id', function(r) {
    window.clsid.client_id = r
  });
  gtag('get', '{{ga4-tracking-id}}', 'session_id', function(r) {
    window.clsid.session_id = r
  });
} else {
  gtag('config', '{{ga4-tracking-id}}', {
    'client_id': window.clsid.client_id,
    'session_id': window.clsid.session_id,
    'cookie_flags': 'SameSite=None;Secure',
    'page_referrer': '{{fsc-referrer}}',
    'page_location': '{{fsc-url}}'
  });
}
</script>

5. Save and name the tag according to your naming rules. We recommend Custom Google Analytics GA4 Configuration.

Set up GA4 Events Tag

Events are the common way to measure all the activities of a user inside the webpage. For more information about events, click here

FastSpring platforms send to the dataLayer variable a list of events that can be used to obtain the ecommerce data and the different steps in the checkout and purchase event. There are two ways to use this information:

1. Use them directly as they come. In this scenario you can directly use the events in Google Analytics with their original name (like FSC-checkoutStep1).
2. Convert the FastSpring events into the standard GA4 events.

The following table shows the FastSpring events pushed to the dataLayer:

Use the FastSpring Events

1. Click Tags > New.
2. Enter FS Events as the tag name or use your naming rules.
3. Select Tag Configuration > Google Analytics: GA4 Event.
4. In the Configuration Tag select “None – Manually Set ID”.
5. Write {{ga4-tracking-id}} for the Measurement ID.
6. Write {{Event}} for the Event Name.
7. Expand More Settings > Ecommerce and select the checkbox for Enable Enhanced Ecommerce Features and Use data layer.
8. Expand Advanced settings > Tag sequencing, check Select Fire a tag before and pick the configuration tag for GA4. Check Don’t fire if the configuration tag fails.
9. Click Save.
10. Click within the Triggering area and select New trigger (the plus sign in the top right corner).
11. Enter the name FastSpring Events.
12. Click within the Trigger Configuration area and select Other > Custom Event.
13. Enter .* in the Event name field and select Use regex matching.
14. Select Some Custom Events and then select Event, starts with, and enter FSC-.
15. Click Save > Save.

Use the GA4 Events

You can use the FastSpring events to build new events in GTM. For example, let’s build a purchase event using the FSC-purchaseComplete event.

1. Click Tags > New.
2. Enter “Purchase Event” as the tag name or use your naming rules.
3. Select Tag Configuration > Google Analytics: GA4 Event.
4. In the Configuration Tag select “None – Manually Set ID”.
5. Write {{ga4-tracking-id}} for the Measurement ID.
6. Write purchase for the Event Name.
7. Expand More Settings > Ecommerce and select Enable Enhanced Ecommerce Features and Use data layer.
8. Expand Advanced settings > Tag sequencing, check Select Fire a tag before and pick the configuration tag for GA4. Check Don’t fire if the configuration tag fails.
9. Click Save.
10. Click within the Triggering area and select New trigger (the plus sign in the top right corner).
11. Enter the name Purchase Event.
12. Click within the Trigger Configuration area and select Other > Custom Event.
13. Enter FSC-purchaseComplete in the Event name field.
14. Select All Custom Events.
15. Click Save > Save.

You can add Event Parameters for your reports using the fsc- variables pushed in the data layer. For a complete list of GA4 events, please review the Google Analytics 4 events reference.

For a complete detail about migrating from Universal to GA4 you can review this link Migrate to Google Analytics 4. For information about the recommended events of GA4 and the compatibility with the FastSpring events please refer to the Appendix I.

Set up the Purchase Event

There are different ways to capture the purchase event. You can directly use the event triggered by FastSpring, you can capture the custom event and then trigger the suggested purchase event, or you can capture the URL /complete page view to trigger the suggested purchase event. More details below:

Use FSC-purchaseComplete as conversion event

Any triggered event can be used as a conversion event. To configure FSC-purchaseComplete as a conversion event you must go to your Google Analytics admin panel.

1. In the property settings select Events.
2. In the Conversion events table search FSC-purchaseComplete.
3. For FSC-purchaseComplete select the toggle Mark as conversion.

Build a purchase event using the FSC-purchaseComplete event

In Google Tag Manager use the instructions for Use the GA4 Events:

1. Click Tags > New.
2. Enter “Purchase Event” as the tag name or use your naming rules.
3. Select Tag Configuration > Google Analytics: GA4 Event.
4. In the Configuration Tag select “None – Manually Set ID”.
5. Write {{ga4-tracking-id}} for the Measurement ID.
6. Write purchase for the Event Name.
7. Expand More Settings > Ecommerce and select Enable Enhanced Ecommerce Features and Use data layer.
8. Expand Advanced settings > Tag sequencing, check Select Fire a tag before and pick the configuration tag for GA4. Check Don’t fire if the configuration tag fails.
9. Click Save.
10. Click within the Triggering area and select New trigger (the plus sign in the top right corner).
11. Enter the name Purchase Event.
12. Click within the Trigger Configuration area and select Other > Custom Event.
13. Enter FSC-purchaseComplete in the Event name field.
14. Select All Custom Events.
15. Click Save > Save.

Use /complete page view as conversion event

To configure the /complete page view as the purchase event follow the next steps:

1. Click Tags > New.
2. Enter “Purchase Event” as the tag name or use your naming rules.
3. Select Tag Configuration > Google Analytics: GA4 Event.
4. In the Configuration Tag select “None – Manually Set ID”.
5. Write {{ga4-tracking-id}} for the Measurement ID.
6. Write purchase for the Event Name.
7. Expand More Settings > Ecommerce and select Enable Enhanced Ecommerce Features and Use data layer.
8. Expand Advanced settings > Tag sequencing, check Select Fire a tag before and pick the configuration tag for GA4. Check Don’t fire if the configuration tag fails.
9. Click Save.
10. Click within the Triggering area and select New trigger (the plus sign in the top right corner).
11. Enter the name Page view complete.
12. Click within the Trigger Configuration area select Page view as a trigger type.
13. In This trigger fires on select Some Page Views.
14. In the rules section select fsc-url as variable, contains as operation and in the last field write /complete.
15. Click Save > Save to save the trigger.
16. Click Save > Save to save the tag.

Troubleshooting

Sometimes it is not easy to identify why no events are received in Google Tag Manager or why no visits are seen in Google Analytics. The easiest way is to diagnose using the debug tools provided by Google Tag Manager through the Tag Assistant. For more detailed information about the debug mode click here — please read this official Tag Manager document before continuing.

Prerequisite for a debug session

Install the Tag Assistant Companion in your web browser.

Understanding the preview mode

In GTM you can have published changes and changes that are still in draft. These changes, although not online, can be tested using the preview mode. The preview mode means that the change will run in the browser from where the preview was launched only. Once all the changes are ready to be sent live you can publish them by generating different versions with change control.

What to look for in the debug session

Basically you have to check that the configuration tags and event tags are triggered. Tag Assistant shows the tags that are launched and their order. Inside each one of them you can see the information that is launched through the dataLayer variable. In the integration with FastSpring you can initially see the launching of the tags in the seller’s website and when the checkout form is opened you can see the launching of the tags on the FastSpring side. Please check the following list:

• Configuration tag is launched on the website side.
• The configuration tag is launched on the FastSpring checkout side.
• Events associated with selecting the payment method, entering the name, entering the address data or any other FastSpring event are triggered.
• The configuration tags should be triggered first and then the event tags. The order is important. In case the configuration tag has not been launched the event tags do not generate measurement in Google Analytics.
• Verify that after a purchase the purchase event is triggered after the configuration tag.

Common Issues

Purchase Event

One of the most common problems is the execution of the purchase event. It is useful when you want to check the conversion of visitors into buyers and helps to optimize campaigns. The GTM FastSpring documentation mentions three alternatives for setting up conversion events associated with the purchase event. If you are not receiving the events properly, we recommend that you use one of the alternatives. Set up purchase event

No analytics hits

Another common problem is seeing events being launched but not seeing visits within Google Analytics. Make sure that the configuration tags are being triggered in the correct order and check the Tag Sequencing settings to ensure that no events are triggered without their configuration tag.

Cross site tracking issues

The reason for cross site tracking configurations is that a visitor who makes a purchase is required to be stored in Google Analytics as a single session from the possible campaign origin to the “Thank you page” or “Complete page”. This allows purchases to be attributed to different campaigns in a precise way and thus to be able to make the right investment decisions on the campaigns. If the registered purchases are not bringing with them the information of the source or referrer, the following points should be checked:

• Web Checkout: Check the configuration of connected domains within the stream in Google Analytics.
  • Check the step: Configure your domains in Google Analytics
• Popup or Embedded Checkout: Check the configuration of the decorateCallback script in the integration with the SBL library. This function explicitly passes the client_id and session_id so that when the checkout window is opened, the same session in which the buyer’s information is being collected is maintained.

Appendix I