Documentation

# Site Alerts

# What is a Site Alert?

A Site Alert displays relevant information to users on certain pages based on custom criteria that you set. For example, if you’d like to show a message to logged-in users on a specific PageBuilder page then you can. You can customize many elements of the site alert including the color scheme, heading, description, call to action text, call to action destination URL, start date, end date, ranking, and cookie settings. A site alert looks like this: site-alert

# Finding the Site Alerts' Configuration

All site alerts are set up in a single PageBuilder reusable page named api__site_alerts. Please make sure you have disabled the WYSIWYG editor for editing HTML before continuing.

  1. Go to Content -> PageBuilder
  2. Search for alerts
  3. The PageBuilder item that handles all the site alerts is named api__site_alerts
  4. If you simply want to look at the current content, click Edit Content on the api__site_alerts.

# Editing Site Alerts

To prevent failures & allow for a quick restoration of previous code, always create a new version of a PageBuilder page for your changes.

# Understanding Site Alerts

There are several configurable options to each site alert and several types of alerts as well. We describe all options below; options are organized in alphabetical order, not in the order of importance.

# bg_color

This will set the theme based on the background color, red value will be used if the value is not specified. Available options are:

  • charcoal
  • plum
  • red
  • teal

The cookie value is required, and it must always be unique. The id must be entered in lower case with no spaces.

This value is used to name a cookie that will be set on a user's computer. Once the cookie is set, the user will not see the alert again for the amount of time specified in cookie_ttl property.

Example cookie values:

  • 2021-12-donation-eoy-1620 - end of year alert that shown on donation form 1620
  • 2021-12-donation-eoy-5071 - end of year alert that shown on donation form 5071
  • 2021-12-fundraise-eoy - generic end of year fundraising alert
  • 2021-12-fundraise-eoy-1130 - end of year fundraising alert shown on event 1130
  • 2021-12-sposor-supporter-center-eoy
  • 2021-10-haiti-earthquake-appeal
  • 2022-01-giving-summary-comming

This is the amount of time the cookie will last in days. The user will see the alert again, after the specified amount of time has passed. If you don't specify a value, then it will last until the user clears the cookie.

# cta_button

This will set the button color, default value hollow-white will be used if no value is specified. Available values are:

  • biscuit_red_text
  • hollow_white
  • red_white_text
  • teal_white_text

# cta_copy

This will set the button text

# cta_destination

This will set the link the button will go to.

# description

This contains the text copy of the alert. HTML code will be accepted if the double quotes are properly escaped.

Example of the description value with HTML that contains escaped quotes:

description": "<div class=\"text--left\">\"To hear regularly from a little guy from halfway around the world. To see him grow up before your eyes. I can't imagine my life without him.\"<br /> -Jeffery, Save the Children Sponsor</div>",

# end_date

This is the end date for the alert. If you leave it empty, then it never ends and will always be displayed.

Date must be written in the ISO format (opens new window) it can be specified as follows:

  • Using the user's local timezone:
    • 2016-12-04T13:30:00 - date and time, local time will be used
    • 2016-12-04 - if using date only, midnight UTC time will be used, not local time, this format is not recommended
  • Using a specific timezone:
    • 2022-01-05T00:00:00Z - date and time uses UTC time zone
    • 2022-01-05T00:00:00-05:00 - uses UTC -5 hrs NY time zone

# id

The id value is highly recommended, and required for donation & teamraiser alert types. The id must be entered in lower case with no spaces.

The id is used to set and determine which page the alert is shown on. If the id value is present in the page's URL, the alert will show. The id is also used to set the name of the cookie on the user's computer if the cookie value is not specified.

Alert types donation or teamraiser are designed to show only on specific pages, therefore the alerts of this type must always contain id of the donation form or TeamRaiser event. Alerts of these types cannot be shown on all or multiple donation or all TeamRaiser pages.

Example id values for an alert that will be shown on the donation form with id 1620 (opens new window)

  • 1620

Example id values for an alert that will be shown on the TeamRaiser even with id 1130 (opens new window)

  • 1130

Alert types custom or custom_cons are designed to show only on specific pages. The id of the alert must match part of the URL string.

Example id value for an alert that will be shown on the cryptocurrency donation page (opens new window)

  • donation__crypto

Example id value for an alert that will be shown on the Find a Fundariser page (opens new window)

  • baf_find_a_fundraiser

# ranking

Only one alert will be shown at a time. To rank them in a certain order, then use this field. Alerts with a higher rank will be shown first.

If there are two or more alerts that a user hasn't seen, then they will be shown the alert with the highest rank. After the user closes the first alert, on page reload the lower ranked eligible alert will display. This will continue until there are no eligible alerts to display.

# start_date

This will be the start date for when the alert will start showing. If you leave the value empty, then the alert will be shown immediately after page publication. See end_date section for format details.

# title

The title can be specified in any text format. The title will be displayed as a heading in the site alert. In the image above, Donation Alert is the title of the alert.

# type

The alert type is required. Only one of the specified values must be used, any other values will generate errors:

  • custom this will display on a custom page where the URL of the page contains the given alert id
  • custom_cons this will display if the user is logged in on a custom page, where the URL of the page contains the given alert id
  • ecomm this will display on all gift catalog pages
  • emergency_cons this will display in a supporter center, if the user is logged in
  • emergency_sponsors this will display in a supporter center, if the user is logged in, and they are currently a sponsor
  • donation this will display on donation pages with a given donation id, if provided
  • registration this will display on registration and sign in pages
  • sponsorship this will display on the sponsorship acquisition page
  • sponsorship_and_cart this will display on sponsorship acquisition pages and cart
  • teamraiser this will display on TeamRaiser pages with a given TeamRaiser id, if provided

# Example

{
	"type": "emergency_cons",
	"title": "",
	"id": "sponsorship-quote",
	"bg_color": "red",
	"description": "Your sponsorship helps ensure children will have a future so that they can grow up healthy, educated, and safe.",
	"cta_button": "hollow_white",
	"cta_copy": "Sponsor A Child",
	"cta_destination": "https://support.savethechildren.org/site/SPageNavigator/sponsorship.html",
	"start_date": "2022-01-05T00:00:00-05:00",
	"end_date": "2022-02-05T00:00:00-05:00",
	"ranking": "2",
	"cookie": "2022-01-spon-quote",
	"cookie_ttl": "4"
},

← Cookies & storage →