Impact Widget Integration Guide

👍
Who should read this:
The webmaster or developer with HTML/CSS -level access to the e-commerce website.

Introduction

This document will walk through the steps of how an Impact Widget gets generated for a store by ShoppingGives.

The first step is deciding which type of impact widget the store would like generated.

a. Charity - displays metrics and details specific to a single nonprofit

b. Portfolio - display metrics and details specific to portfolio

c. Store Total Donation - displays the total donation amount generated by the store without cause information

Next, store provides the following information to ShoppingGives:

a. Portfolio Name, Charity Name, or Charity EIN (if applicable)

b. Widget Title (optional)

c. Widget Description (optional)

The store should then determine which >> Data Tokens they want displayed within the widget.
After the tokens have been defined, the store can then Create the HTML to incorporate them and provide the HTML to ShoppingGives.
ShoppingGives will take all information received to generate a line of code for the store’s Impact Widget.
Once the store receives the Impact Widget iFrame Code from ShoppingGives, that code can be placed anywhere in their site’s HTML that it’s expected to appear.

Impact Widget numbers update whenever a new donation comes in that's relevant to the widget or when the Refresh Impact Widget endpoint is called.

Please note that the API uses the JSON API specification.

Data Tokens

Please note all tokens are optional.

General Widget Information

Name	Token	Description
Store Name	%StoreName%	The name of store
Title	%Title%	If provided during setup, the title of the widget
Description	%Description%	If provided during setup, text describing this widget
Last Update At	%LastUpdateAt%	Identifies when the widget metrics were last updated

Donation Information

Donation information is auto-calculated by the ShoppingGives services.

Name	Token	Description
Total Donations	%TotalDonations%	The total dollar amount donated to charity or portfolio

Charity Related Tokens

Charity information is auto-generated by the ShoppingGives services.

Name	Token	Description
Charity Name	%CharityName%	The name of the charity
Charity Full Address	%CharityFullAddress%	The full address of the charity
Charity Street	%CharityStreet%	Only the charity’s street address
Charity City	%CharityCity%	Only the charity’s city name
Charity State	%CharityState%	Only the charity’s state name
Charity Zip	%CharityZip%	Only the charity’s zip code
Charity Suite	%CharitySuite%	Only the charity’s suite
Charity Description	%CharityDescription%	The description associated with charity

Portfolio Related Tokens

Portfolio information is auto-generated by the ShoppingGives services. Since a portfolio can have up to four (4) charities associated with it, the charity related tokens below will have a numeric value from 1 to 4 appended to the end.

Name	Token	Description
Portfolio Name	%PortfolioName%	The portfolio name
Portfolio Headline	%PortfolioHeadline%	Headline associated with portfolio
Charity Name n	%CharityNameN%	The name of the nth charity
Charity Full Address n	%CharityFullAddressN%	The full address of the nth charity
Charity Street n	%CharityStreetN%	Only the nth charity’s street address
Charity City n	%CharityCityN%	Only the nth charity’s city name
Charity State n	%CharityStateN%	Only the nth charity’s state name
Charity Zip n	%CharityZipN%	Only the nth charity’s zip code
Charity Suite n	%CharitySuiteN%	Only the the nth charity’s suite
Charity Description n	%CharityDescriptionN%	The description associated with the nth charity

Impact Widget HTML Examples

Charity

<div id="sg-impact-widget-container-1" class="sg-impact-widget-container">
  <h3 class="sg-impact-widget__title">%Title%</h3>
  <h4 class="sg-impact-widget__description">%Description%</h4>
  <p class="sg-impact-wiget__store-name">%StoreName% has raised</p>
  <p class="sg-impact-wiget__total-donations">$%TotalDonations%</p>
  <p class="sg-impact-wiget__charity-name">for %CharityName%</p>
</div>

<style>
.sg-impact-widget-container {
  border: 2px solid #000000;
  font-family: sans-serif;
  font-size: 12px;
  padding: 10px 10px;
  text-align: center;
}
.sg-impact-widget__title {
  font-size: 1.3em;
  margin: 0px;
}
.sg-impact-wiget__total-donations {
  font-size: 20px;
  font-weight: bold;
}
</style>

Portfolio

<div id="sg-impact-widget-container-1" class="sg-impact-widget-container">
  <h3 class="sg-impact-widget__title">%Title%</h3>
  <p class="sg-impact-widget__description">%Description%</p>
  <p class="sg-impact-wiget__store-name">%StoreName% has raised</p>
  <p class="sg-impact-wiget__total-donations">$%TotalDonations%</p>
  <p class="sg-impact-wiget__charity-name">for %PortfolioName% that supports:</p>
  <ul class="sg-impact-widget__charity-list">
  	<li class="sg-impact-widget__charity-list-item">%CharityName1%</li>
  	<li class="sg-impact-widget__charity-list-item">%CharityName2%</li>
  	<li class="sg-impact-widget__charity-list-item">%CharityName3%</li>
  	<li class="sg-impact-widget__charity-list-item">%CharityName4%</li>
  </ul>
</div>

<style>
.sg-impact-widget-container {
  border: 2px solid #000000;
  font-family: sans-serif;
  font-size: 12px;
  padding: 10px 10px;
  text-align: center;
}
.sg-impact-widget__title {
  font-size: 1.3em;
  margin: 0px;
}
.sg-impact-wiget__total-donations {
  font-size: 20px;
  font-weight: bold;
}
.sg-impact-widget__charity-list {
  list-style: none;
  padding: 0px;
}
</style>

Store Total Donation

<div id="sg-impact-widget-container-1" class="sg-impact-widget-container">
  <p class="sg-impact-wiget__store-name">%StoreName% has raised a total of</p>
  <p class="sg-impact-wiget__total-donations">$%TotalDonations%</p>
  <p class="sg-impact-wiget__text">in donations</p>
</div>

<style>
.sg-impact-widget-container {
  border: 2px solid #000000;
  font-family: sans-serif;
  font-size: 12px;
  padding: 10px 10px;
  text-align: center;
}
.sg-impact-wiget__total-donations {
  font-size: 20px;
  font-weight: bold;
}
</style>

Impact Widget iFrame Code

Place the Impact Widget iframe line of code in the location that you want it to appear.

Parameter	Type	Description	Required	Default
store-id	text	Store Id - provided by ShoppingGives	Yes	n/a
impact-widget-id	text	Impact Widget Id - provided by ShoppingGives	Yes	n/a

<!-- TEMPLATE -->
<iframe src="https://cdn.shoppinggives.com/widgets/impact/{store-id}/{impact-widget-id}.html" style="border:0px;height:auto;width:auto;"></iframe>

<!-- EXAMPLE -->

<iframe src="https://cdn.shoppinggives.com/widgets/impact/ab123456-c78d-9ef0-g1h2-345i678j90k1/54942104-4fe5-447e-8a96-2a27f26a1264.html" style="border:0px;height:auto;width:auto;"></iframe>

🚧
The iframe height/width may need to be adjusted depending on the size of the widget generated.

Refresh Impact Widget

📘
NOTE: The Impact Widget numbers will update whenever a new donation comes in that's relevant to the widget or when this refresh endpoint is called.

POST /widget/widget/<span style="color: green">54942104-4fe5-447e-8a96-2a27f26a1264</span>/refresh

POST https://impactwidget.api.shoppinggives.com/widget/widget/{impact-widget-id}/refresh

Expected Headers


x-store-id	x-store-id Store Id - Provided by ShoppingGives
x-store-api-key	Store API Key - Provided by ShoppingGives
content-type	application/json
accept	/

Example Call

POST /widget/widget/54942104-4fe5-447e-8a96-2a27f26a1264/refresh

👍Who should read this:

Introduction

Data Tokens

General Widget Information

Donation Information

Charity Related Tokens

Portfolio Related Tokens

Impact Widget HTML Examples

Charity

Portfolio

Store Total Donation

Impact Widget iFrame Code

🚧

Refresh Impact Widget

📘

Expected Headers

Example Call

👍
Who should read this: