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:

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.

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

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();
console.log(sgData);

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.