Leveraging Events & Data Layer

Introduction to ShoppingGives Data Layer and Events

The ShoppingGives Data Layer and Events framework allows merchants to leverage the data and events from our widgets and campaigns directly within their online stores. By leveraging this framework, merchants can enhance the shopping experience, pull data into downstream systems for reporting, sales audits, or personalization.

Best Practices and Use Cases

  • Personalization: Use the data layer to personalize the shopping experience by highlighting causes important to the customer.
  • Reporting and Analytics: Analyze event data to understand customer preferences and engagement with charitable features.
  • Enhancing Customer Experience: Use insights from the data layer and events to improve and tailor the donation process, encouraging more participation and contributions.

Understanding the SG Data Layer

The Data Layer is a structured format designed to hold and manage information about the store, customers, donations, and causes. It is essential for tracking, personalization, and analytics purposes. The key components of the data layer include:

Event DataDescription
storeContains information about the store's donations, chosen causes, and cause IDs.
storeDonationThe total donation amount allocated by the store.
storeCausesA list of causes the store supports.
storeCauseIdsThe IDs associated with the store's chosen causes.
customerHolds data related to the customer's donation preferences and chosen causes.
customerDonationThe total donation amount allocated by the customer.
customerCausesA list of causes the customer supports.
customerCauseIdsThe IDs associated with the customer's chosen causes.
donationThe total donation amount (combining store and customer donations).
causesNamesNames of all available causes for donations.
causeIdsIDs of all available causes for donations.
store: {
   storeDonation: '$2.06',
   storeCauses: 'cause1, cause2, cause3',
   storeCauseIds: [562345, 784554, 654786]
customer: {
   customerDonation: '$5.04',
   customerCauses: 'cause4, cause5, cause6',
   customerCauseIds: [968574, 45437,565435]
donation: '$7.10',
causesNames: 'cause1, cause2, cause3, cause4, cause5, cause6',
causeIds: [562345, 784554, 654786, 968574, 45437,565435]

Accessing the Data Layer:

You can access the data set by ShoppingGives in the Data Layer when known donation data is available. Data becomes available when the donation widget loads. You can access the dataLayer when the event 'sgDonation' is fired.

Capturing the 'sgDonation' Event from the Data Layer

To capture the sgDonation event from the data layer, you can use the Array.prototype.find method to search through the dataLayer array. This method will iterate over all objects in the dataLayer and return the first object that matches the condition provided in the callback function. In this case, the condition checks whether the event property of an object equals 'sgDonation'.

Below is the code snippet for this operation:

// Capture the 'sgDonation' event from the data layer  
let sgDataEvent = window.dataLayer.find(obj => obj.event === 'sgDonation');  
// This code assigns the sgDonation event to the sgDataEvent variable.
// If no such event is found within the dataLayer, the variable will be undefined.

Handling the 'sgDonation' Event Data
After capturing the sgDonation event from the data layer, it is crucial to ensure the event exists before attempting to access its data. The sgDonation event contains important information regarding donations and chosen causes. Below is a code snippet that demonstrates how to safely access data within the sgDonation event:

// Ensure the 'sgDonation' event exists in the data layer
if (sgDataEvent) {
    // Safely access the data within the 'sgDonation' event
    let store = sgDataEvent["sg-donation-data"].store;
    let storeDonation = sgDataEvent["sg-donation-data"].storeDonation;
    let storeCauses = sgDataEvent["sg-donation-data"].storeCauses;
    let storeCauseIds = sgDataEvent["sg-donation-data"].storeCauseIds;
    let customer = sgDataEvent["sg-donation-data"].customer;
    let customerDonation = sgDataEvent["sg-donation-data"].customerDonation;

Overview of ShoppingGives Widgets widget classes and user interactions

This table structures the tracking for various user interactions with the ShoppingGives widget and related features. Each row describes a specific data element related to user actions, the rule that defines when this action is clicked, the type of events that can be captured, the class associated with the action, and the values displayed during the event.

Data ElementRuleCaptured EventsClassValues to Captured
Widget VisibilityShoppingGives Widget VisibilityVisibility of ShoppingGives Widget'sg-widget'{page_path}
Widget ClicksShoppingGives Widget ClickAny element on the widget is clicked 'sg-widget'{page_path},
Featured Cause SelectUser selects a featured causeFeatured Cause Selected'sg-featured-selected'{page_path}
Search Cause SelectUser selects a cause from search resultSearch Caused Selected'sg-select-searched-cause'{page_path}
Learn More ClicksUser clicks on Learn MoreLearn More Clicked'sg-learn-more-button'{page_path}
Add on Donation ClickedUser adds on donationAdd on Donation selected by user'sg-add-on'{page_path},
Cause NameCause is knownCause Selected via Featured, Search or Default. 'sg-cause-name'{page_path}
Round Up Donation SelectedUser opts for round-up donationRound Up Donation selected by user'sg-round-up'{page_path},
Merchant DonationThe value of the Merchant DonationIf donation amount from the Merchant is available 'sg-merchant-donation'{page_path},
Customer Add On DonationThe value of the Add On DonationIf customer Add On donation amount is available'sg-selected-add-on-donation'{page_path},
Customer Round Up DonationThe value of the Round Up Donationif customer Round Up donation amount is available'sg-selected-round-up-donation'{page_path},

Leveraging Campaign and Segment Data via Windows Variables

In addition to leveraging the Data Layer and Widget Event data you can leverage Campaign and Segment Data provided as windows variables related to the campaign and the segment the user is in when they engage with the widget.

Provided Windows Variables

Window ValueWindow PathTypeDescription
segmentNamewindow.sgConfig.segmentNamestringThe name of the current segment you defined in portal that the user's session is identified and active in.
segmentIdwindow.sgConfig.segmentIdstringThe unique Id that correlates to the Segment Name of the current segment you defined in portal that the user's session is identified and active in.
campaignNamewindow.sgConfig.campaignNamestringThe name of the current Campaign you defined in portal that the user's session is identified and active in based on the user segment and priority of the campaign in the portal.
campaignIdwindow.sgConfig.campaignIdstringThe unique Id that correlates to the current Campaign you defined in portal that the user's session is identified and active in based on the user segment and priority of the campaign in the portal.

Access the windows variables

To efficiently access and use the provided window variables related to campaign and segment data, you can create a JavaScript function. This function will extract the relevant information from the window.sgConfig object, allowing you to leverage these details for analytics, personalization, or any other purpose you see fit. Note, these are not pushed to the Data Layer because they are dynamic and can update or change based on your defined segment created in the portal.

Here's an example of such a function:

function getSegmentAndCampaignData() {
  // Initialize an object to hold the segment and campaign data
  const data = {
    segmentName: '',
    segmentId: '',
    campaignName: '',
    campaignId: ''

  // Check if the sgConfig object exists in the window
  if (window.sgConfig) {
    // Extract the segment and campaign information
    data.segmentName = window.sgConfig.segmentName || 'Not Available';
    data.segmentId = window.sgConfig.segmentId || 'Not Available';
    data.campaignName = window.sgConfig.campaignName || 'Not Available';
    data.campaignId = window.sgConfig.campaignId || 'Not Available';
  } else {
    // Log a message if sgConfig is not found
    console.warn('sgConfig object is not found in the window. Make sure it is correctly initialized.');

  // Return the collected data
  return data;

// Example usage
const sgData = getSegmentAndCampaignData();

This function getSegmentAndCampaignData checks if the window.sgConfig object is available and extracts the segmentName, segmentId, campaignName, and campaignId. If the sgConfig object does not exist, it logs a warning message indicating the object is not found, preventing any potential errors from accessing undefined properties. You can call this function whenever you need to access these details, for example, when a user interacts with the widget or during page load to tailor content or analytics based on the user's segment and campaign data.

Integrating widget events and interactions into your Analytics Platform

Integrating the ShoppingGives widget interactions into analytics platforms such as Google Analytics 4 (GA4) or Adobe Analytics offers valuable insights into how users engage with donation features on your site. By tracking specific events and user actions outlined in the table, you can generate detailed analytics that help understand user behavior, optimize the donation process, and enhance overall user experience. Here's an introductory guide on leveraging these data elements for analytics in GA4 and Adobe Analytics:

For Google Analytics 4 (GA4)

In GA4, you can track user interactions by sending events. Each action, such as widget visibility, clicks, and cause selections, can be captured as a distinct event. To do this:

Identify Events: Use the 'Actions (Captured Events)' column to define the events you want to track, such as 'Visibility of ShoppingGives Widget' or 'Clicks on ShoppingGives Widget'.

Capture Event Parameters: For each event, identify additional parameters you want to capture, such as page_path, action, or cause_name, to provide context to the event.

Implement Event Tracking: Utilize the gtag.js library or Google Tag Manager to capture these events. For example, to track widget clicks, you might add event listeners in your code that trigger when the specified classes are interacted with, sending an event to GA4 with the relevant parameters.

document.querySelectorAll('.sg-widget').forEach(widget => {
  widget.addEventListener('click', function() {
    gtag('event', 'shoppinggives_widget_click', {
      'page_path': window.location.pathname,
      'action': this.classList.contains('sg-featured-select') ? 'featured_select' : 'other_action'

For Adobe Analytics

In Adobe Analytics, tracking is typically configured through rules in Adobe Launch, which allows for sophisticated tracking setups:

Define Rules: Based on the 'Actions (Captured Events)' and 'Class', set up rules in Adobe Launch to listen for specific user interactions. Each rule can correspond to an action, like widget clicks or cause selections.

Set Up Data Elements: Create data elements in Adobe Launch that correspond to the values you wish to capture (page_path, cause_name, etc.). These elements can then be used within your rules to capture the context of each event.

Configure Event Tracking: For each rule, configure the appropriate tracking method to send data to Adobe Analytics. This might involve setting custom events or eVars to capture specific interaction details.

For example, a rule could be set up to trigger when an element with the class 'sg-learn-more-button' is clicked, capturing the page_path and sending it along with a custom event to Adobe Analytics.