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
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
Updated almost 3 years ago