SimplicityBlocks™ Documentation

Overview

SimplicityBlocks™ is a service that allows you to easily create a universally distributable web widget using any front-end/back-end framework of your choice. Whether you use React, Angular, VueJS, vanilla JS, JQUERY, etc. your widget can be embedded in any web page that supports modern browsers.

Throughout our site and this documentation, we use a simple rating widget in order to demonstrate the various concepts involved with creating an embeddable widget and communicating with the widget via attributes and events. This rating widget is a simple vanilla JS app. It has two parameters that need to be set when loaded: one is for the main heading and the other is for the subheading above the text box.

Getting Started

To start with SimplicityBlocks™ you need to first sign up for a test account. A test account does not require you to enter any credit card information. You can build as many blocks as you like, but monthly requests are limited to 1,000. Also, test accounts cannot be used for live deployments as they are intended for test purposes only. When you are ready to launch your embeddable widget to a production environment you need to upgrade your account to a paid account. Your account is billed monthly based on the plan you selected.

Signup

You can sign up for a SimplicityBlocks™ test account from the “Get Free Test Account” button on the home page or by clicking the “Sign Up” link in the top right of the site’s header.

No credit card information is required to set up a test account. An email address is required and needs to be verified before being able to log into your account. You will also need to agree to the terms of service.

The email will be from support@simplicityblocks.com so you may need to whitelist this address / domain in your email client.

Once your email is verified you can log in and start creating blocks.

Upgrade Account

Once you have created blocks in your test account and want to distribute your widget you will want to upgrade your account to a pro account.

To upgrade your account click on Account in the main menu.

The main account page will show the status of your account. In the section that shows “Your account is a test account” there is a link to “Upgrade Account Page”.

In the Upgrade Account Page you select a plan that is best for you and enter your credit card information. Once that information is successfully processed your account will be switched to a pro account.

Creating Blocks

List Blocks

From the main menu select “Manage Blocks”. Depending on whether or not you have created any blocks yet you will see one of the following two screens. The “Add Block” button is always there to create a new block.

If there is a list of existing blocks, you have the option of modifying or deleting the block.

OR

Add New Block

When you add a new block the initial screen will show “New Block” next to the Block ID heading and a blank description. You can add any description you like. It is used for sorting the list in the display blocks page.

The block configuration screen consists of three parts: Block identification and status; Block configuration; Preview

Block Identification and Status

Once you click on the “Add New” button a block id is assigned to the block and the ‘Add New” button changes to an update button.

As you are working on configuring a new block it is a good idea to regularly click on the “Update” button in order to save your work.

Preview

The preview section shows the preview of the launcher inside the box that is outlined with a dashed line. The launcher changes in real time as you make changes. Please note that it does not activate your widget and does not show animations. It is just a visual preview of the core launcher body.

The “Browser Preview” button will display your widget in a sample web page that opens in another browser window instance. Depending on how you configure your widget is how you determine which preview version to select. The “Refresh Preview” button wil reload the preview window. This is used to view changes you have saved.

• Grow from Top
• Overlay
• Inline
• Inline Bottom

Preview page samples:

Grow from Top

The grow from top preview is a preview mode for one specific animation setting (Grow from Top).

Overlay

The overlay preview displays launchers that are configured as overlay.

Inline

The inline preview displays launchers configured as inline. This preview mode also allows you to resize the container that holds the launcher (and widget if also configured as inline). To resize the container grab the handle at the bottom right and resize to your desired size.

NOTE: The browser preview function is just a quick check of your widget embedded in a page. The best test is for you to use your own test page that best represents the audience that will use your widget and test it there.

Block Configuration

The block configuration section is divided into 6 separate tabs:

• Launcher Body
• Launcher Text
• Launcher Icon
• Launcher Hover
• Widget
• Embed Code

Launcher Body

The launcher body is the overall shape, size and color of your launcher.

Launcher Body Settings

Overlay/Inline/None

This setting determines how the launcher body is rendered on the host page.

Overlay

When set as overlay the launcher appears over the web page content. A typical example of this would be a chat widget that shows in the lower right-hand side of a page. When set as overlay the Launcher Position setting below will define where on the page the launcher will be displayed.

Inline

When set as inline the widget will appear as a child of a container element in the web page. In this mode the individual in control of the page that is using your widget has control of where the widget will appear. If the widget size isn’t matched to the parent container, the Launcher Position setting will set the position within the parent container.

None

Setting to none will simply not use a launcher. Your widget will be immediately displayed.

Shadow

Shadow sets the shadow settings of the launcher body. This is CSS for the box-shadow setting.

Example values to enter here:

• none (or blank)
• 60px -16px teal
• 10px 5px 5px black
• 2px 2px 2px 1px rgba(0, 0, 0, 0.2)

Pass Events

This setting is intended for use when you are taking advantage of the slot capabilities of a SimplicitBlock (i.e., embedding a block within a block or embedding your own HTML inside the opening and closing tags of a SimplicityBlock (<simplicity-block>xxx</simplicity-block>).

When set (checked on) it will allow events to pass through to the embeded code or block instead of launching the widget as it does normally. Note that if you are using this to create your own customized launcher, you will be responsible for launching the widget in script.

Height

Height sets the height of the launcher body. This is a CSS value for height.

Example values to enter here:

• 150px
• 10em
• 30%
• auto

Width

Width sets the width of the launcher body. This is a CSS value for width.

Example values to enter here:

• 150px
• 10em
• 30%
• auto

Background Color

Background color sets the background color of the launcher body. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Launcher Position

The launcher position setting defines where the launcher body is positioned in relation to the viewport (for overlay) or within the parent (for inline). The 9 radio button setting choices are top left, top center, top right, middle left, middle center, middle right, bottom left, bottom center and bottom right.

Border Width

The launcher border width sets the width of the launcher body border.

Example values to enter here:

• 0px
• 3px
• .2em
• thick
• 0 4px 8px 12px

Border Color

Border color sets the border color of the launcher body’s border. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Border Radius

The border radius setting sets the CSS border-radius of the launcher body’s border (if there is a border).

Example values to enter here:

• 0 (or leave empty)
• 20px
• 10% 30% 50% 70%
• 50%

Launcher Margin

The launcher margin sets the CSS margin of the launcher body in relation to the view port (for overlay) or the parent element (for inline).

Example values to enter here:

• 16px
• 1em
• 5%
• 10px 50px 20px

Launcher Text

The launcher text is the text that appears within the launcher body. This can be left blank if for example your launcher only contains an icon or image.

Text

This is the text that shows up in your launcher.

Text Position

This is the position of the text within the launcher body. The 9 radio button setting choices are top left, top center, top right, middle left, middle center, middle right, bottom left, bottom center and bottom right.

Text Margin

This is the margin of the text in relation to the inside of the body of the launcher.

Example values to enter here:

• 16px
• 1em
• 5%
• 10px 50px 20px

Font

The dropdown box for the font selects the browser-safe font family for the text.

The choices are:

• default
• Garamond Serif
• Georgia Serif
• Helvetica-Arial Sans-Serif
• Impact Sans-Serif
• Monospace
• System
• Times Serif
• Trebuchet Sans-Serif
• Verdana Sans-Serif

Font Size

The font size setting defines the CSS font size of the text.

Example values to enter here:

• 14px
• 1.2em
• x-small
• smaller

Font Style

The font style setting lets you add a bold or italic style to the font.

The choices are:

• default
• bold
• italic
• bold and italic

Font Color

Font color sets the font color of the text. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Launcher Icon

The launcher icon (if you choose to have one) can be an svg, jpg, png or gif file.

Icon Height

The icon height is a CSS height value that sets the height of the icon. PLEASE NOTE: If you choose an SVG image as your icon, there may be limits on the effects of the height settings.

Example values to enter here:

• 150px
• 10em
• 30%
• auto

Icon Width

The icon width is a CSS width value that sets the width of the icon. PLEASE NOTE: If you choose an SVG image as your icon, there may be limits on the effects of the width settings.

Example values to enter here:

• 150px
• 10em
• 30%
• auto

Icon Margin

This is the margin of the icon in relation to the text and the inside of the body of the launcher.

Example values to enter here:

• 16px
• 1em
• 5%
• 10px 50px 20px

Remove Icon

If you have set up an icon and wish to remove it simply click on the Remove Icon button.

Icon Line Color (SVG Only)

Icon line color sets the line color value of the SVG image. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color. PLEASE NOTE: Not all SVG images will support this setting.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Icon Background Color(SVG Only)

Icon background color sets the background color value of the SVG image. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color. PLEASE NOTE: Not all SVG images will support this setting.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Icon to Text Position

This setting defines the position of the icon in relation to the text. The options are top, right, bottom or left.

Launcher Hover

The launcher hover settings allow you to create desired effects for when a user places their cursor over the launcher.

Hover Cursor

This dropdown list allows you to select the type of cursor you want to display when the user hovers over the launcher.

Hover Background Color

The hover background color sets the background color of the launcher body for when the cursor is placed over the launcher body.. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Hover Border Color

The hover border color sets the border color of the launcher body for when the cursor is placed over the launcher body.. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Hover Text Color

The hover text color sets the color of the launcher text for when the cursor is placed over the launcher body.. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Hover Icon Line Color (SVG ONLY)

The Hover Icon line color sets the line color value of the SVG image when the cursor is placed over the launcher body. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color. PLEASE NOTE: Not all SVG images will support this setting.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Hover Icon Background Color (SVG Only)

The Hover Icon background color sets the background color value of the SVG image when the cursor is placed over the launcher body. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color. PLEASE NOTE: Not all SVG images will support this setting.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Hover Shadow

The Hover Shadow sets the shadow settings of the launcher body for when the cursor is over the launcher body. This is CSS for the box-shadow setting.

Example values to enter here:

• none (or blank)
• 60px -16px teal
• 10px 5px 5px black
• 2px 2px 2px 1px rgba(0, 0, 0, 0.2)

Hover Margin

The hover launcher margin sets the CSS margin of the launcher body in relation to the view port (for overlay) or the parent element (for inline) for when the cursor is over the launcher body.

Example values to enter here:

• 16px
• 1em
• 5%
• 10px 50px 20px

Launcher Animation

The launcher animation settings allow you to implement effects on the launcher such as fly in from the top, zoom in, fade in, rotate or a combination if these. Additionally, implementing an animation allows you to set a delay which you can use to have your launcher appear after a set amount of time after page load.

Use Animation

If you wish to use animation for the launcher you must set this to "Use animation". If you do not want to use animation, set this to "Do not use animation".

Animation delay

The animation delay sets the timing of a delay in seconds [s] or milliseconds [ms] before the launcher animation begins.

Example values to enter here:

• 0.5s or 500ms (same thing, delays 1/2 second)
• 120s (delays 2 minutes)
• 3s
• 750ms

Animation Duration

The animation duration sets the a mount of time that the animation will use to fully execute. For example if you set the animation to fly in from the top left (and the launcher is set to appear in the bottom right) and set the animation duration to 3s (3 seconds), it will take 3 seconds for the launcher to go from the top left to the bottom right.

Example values to enter here:

• 0.5s or 500ms (same thing, animation lasts 1/2 second)
• 3s
• 750ms

Animation Timing Function

The animation timing function sets how your animaion behaves through the duration. For example when set to linear the animation will sequence throught at the same rate, when set to ease-in-out it will start slow, go faster and then end slow.

Example values to enter here:

• linear
• ease-in-out
• steps(5, end)
• cubic-bezier(0.1, -0.6, 0.2, 0)

Fly/Slide/Grow In

The fly/slide/grow in dropdown list lets you choose from some pre-defined motion effects. Most of the choices here are self-explanatory. The fly in options will typically be used in opposite to where the launcher position is set. For example, if your launcher position is set to be in the lower right you would want to use Fly in from top, Fly in from top left or Fly in from left. The slide in options are designed to move the width or height of the launcher. Example usage of this is if your launcher is set to the bottom right position you would want to slide in from the bottom or slide in from the right. The grow from top is a special use case where the effect is specifically designed to grow down from the top of the page. PLEASE NOTE: The grow from top will only work properly if the launcher is configured as inline.

Zoom from (start%)

The zoom animation setting will either grow or shrink the launcher to the original size during the animation duration. You can start as a multiple of the original size or a fraction of the original size. Values can be expressed as percentages (using %) or as decimal units where 1 = 100% (2 would = 200%, .5 = 50%, etc.)

Example values to enter here:

• 50% or .5
• 100% or 1 (no zoom)
• 300% or 3

Rotate (degrees [deg])

The rotate setting lets you rotate the launcher as part of the animation. One full rotation is 360deg. You can rotate a partial turn (e.g., 180deg) or rotate multiple times (720deg would rotate 2 full turns).

Example values to enter here:

• 0deg (no rotation)
• 180deg (1/2 turn)
• 1440deg (4 full turns)

Fade

The Fade setting animates the opacity of the launcher. Values can be expressed as percentages (using %) or as decimal units where 1 = 100% (1 would = 200%, .75 = 75%, .5 = 50%, etc.)

Example values to enter here:

• 1 or 100% (no fade effect
• 0% or 0 (start from invisible and fade to fully visible)
• .5 or 50% start from 1/2 opacity

Widget

The widget tab lets you configure your widget that displays with the block either when the launcher is activated or immediately when configured as inline with no launcher.

Overlay/Inline

Overlay

When set as overlay the widget appears over the web page content. A typical example of this would be a chat widget that shows in the lower right-hand side of a page. When set as overlay the Widget Position setting below will define where on the page the widget will be displayed.

Inline

When set as inline the widget will appear as a child of a container element in the web page. In this mode the individual in control of the page that is using your widget has control of where the widget will appear. If the widget size isn'’'t matched to

Modal/Nonmodal

Modal

When modal is selected the overlay widget and its background will not let click events flow through to the page below.

Nonmodal

When nonmodal is selected click events will go through to the background page.

Widget Position

The widget position setting defines where the widget is positioned in relation to the viewport (for overlay) or within the parent (for inline). The 9 radio button setting choices are top left, top center, top right, middle left, middle center, middle right, bottom left, bottom center and bottom right.

Widget Preload

The widget preload setting defines whether or not the widget gets preloaded at the same time the launcher loads or when the launcher gets clicked. When checked it gets preloaded, when unchecked the widget gets loaded when the launcher gets clicked.

Height

Height sets the height of the widget body. This is a CSS value for height.

Example values to enter here:

• 400px
• 10em
• 30%
• 80vh

Width

Width sets the width of the widget body. This is a CSS value for width.

Example values to enter here:

• 400px
• 10em
• 30%
• 80vw

Widget Margin

The widget margin sets the CSS margin of the widget body in relation to the view port (for overlay) or the parent element (for inline).

Example values to enter here:

• 16px
• 1em
• 5%
• 10px 50px 20px

Background Color

Background color sets the background color of the widget overlay background. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Close Icon Width

The close icon width is the diameter of the close icon circle that shows on the top right of the widget. If you do not want to use the pre-defined close icon you can put 0px for a value here. See the Widget Communication section below to see how to send a close command from within your widget.

Example values to enter here:

• 16px
• 1em

Close Icon Color

Close Icon color sets the color of the round close button that shows on the top right of the widget. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

• red
• #00ff00
• rgb(214, 122, 127)
• rgba(57,96,61,0.43)

Close Icon Offset Top

This setting positions the close button over the top edge of the widget. Using an offset can place the close button icon over the edge of the corner.

Example values to enter here:

• 16px
• 1em

Close Icon Offset Right

This setting positions the close button over the right edge of the widget. Using an offset can place the close button icon over the edge of the corner.

Example values to enter here:

• 16px
• 1em

Widget URL

This is the fully qualified URL of where your widget is hosted.

It is recommended to use a secure URL (i.e., https).

You will need to make sure that your response allows your widget to be loaded in an iframe. This is typically accomplished by removing the X-Frame-Options header from the response.

Widget Attributes

You can define as many widget attributes as you like. Enter each attribute name separated by commas.

When your widget is loaded in the Simplicity Block the attributes and the values that your user placed in them will get passed to your widget as URL parameters. You can then read those parameters and take appropriate action.

If the user of your Simplicity Block programmatically sets an attribute value, that will cause an event and the Simplicity Block will reload he widget with the new value in the URL parameters.

Allowed Domains

If you want all domains to be allowed to use your Simplicity Block, enter an * for the value here.

If you wish to restrict access to your Simplicity Block to select domains, enter the domain names here. You can use * as the subdomain. For example: *.mydomain.com. Multiple entries need to be separated by commas.

If you have restricted the access to your Simplicity Block to specific domains, requests from domains that are not allowed will simply not display. These unallowed requests will also NOT COUNT toward your monthly usage.

Preview Attributes

The preview attributes are simply values you can define that will get passed to your widget when using our preview functionality. These need to be separated by commas. For example:

rh=Rate This Page,ch=Leave a Comment

Widget Animation

The widget animation settings allow you to implement effects on the widget such as fly in from the top, zoom in, fade in, rotate or a combination if these. Additionally, implementing an animation allows you to set a delay which you can use to have your widget appear after a set amount of time after page load. The delay is most useful in cases where you do not use a launcher and directly display your widget to the user. When the widget closes the animation runs in reverse.

Use Animation

If you wish to use animation for the widget you must set this to "Use animation". If you do not want to use animation, set this to "Do not use animation".

Animation delay

The animation delay sets the timing of a delay in seconds [s] or milliseconds [ms] before the widget animation begins.

Example values to enter here:

• 0.5s or 500ms (same thing, delays 1/2 second)
• 120s (delays 2 minutes)
• 3s
• 750ms

Animation Duration

The animation duration sets the a mount of time that the animation will use to fully execute. For example if you set the animation to fly in from the top left (and the widget is set to appear in the bottom right) and set the animation duration to 3s (3 seconds), it will take 3 seconds for the widget to go from the top left to the bottom right.

Example values to enter here:

• 0.5s or 500ms (same thing, animation lasts 1/2 second)
• 3s
• 750ms

Animation Timing Function

The animation timing function sets how your animaion behaves through the duration. For example when set to linear the animation will sequence throught at the same rate, when set to ease-in-out it will start slow, go faster and then end slow.

Example values to enter here:

• linear
• ease-in-out
• steps(5, end)
• cubic-bezier(0.1, -0.6, 0.2, 0)

Fly/Slide/Grow In

The fly/slide/grow in dropdown list lets you choose from some pre-defined motion effects. Most of the choices here are self-explanatory. The fly in options will typically be used in opposite to where the widget position is set. For example, if your widget position is set to be in the lower right you would want to use Fly in from top, Fly in from top left or Fly in from left. The slide in options are designed to move the width or height of the widget. Example usage of this is if your widget is set to the bottom right position you would want to slide in from the bottom or slide in from the right.

Zoom from (start%)

The zoom animation setting will either grow or shrink the widget to the original size during the animation duration. You can start as a multiple of the original size or a fraction of the original size. Values can be expressed as percentages (using %) or as decimal units where 1 = 100% (2 would = 200%, .5 = 50%, etc.)

Example values to enter here:

• 50% or .5
• 100% or 1 (no zoom)
• 300% or 3

Rotate (degrees [deg])

The rotate setting lets you rotate the widget as part of the animation. One full rotation is 360deg. You can rotate a partial turn (e.g., 180deg) or rotate multiple times (720deg would rotate 2 full turns).

Example values to enter here:

• 0deg (no rotation)
• 180deg (1/2 turn)
• 1440deg (4 full turns)

Fade

The Fade setting animates the opacity of the widget. Values can be expressed as percentages (using %) or as decimal units where 1 = 100% (1 would = 200%, .75 = 75%, .5 = 50%, etc.)

Example values to enter here:

• 1 or 100% (no fade effect
• 0% or 0 (start from invisible and fade to fully visible)
• .5 or 50% start from 1/2 opacity

Embed Code

Once you are done configuring your block you can get your embed code.

In the Embed Code tab click on the ‘Get Embed Code’ button and the text box will display the component tag with the required Simplicity Block ID (sbid) as well as any attributes you have defined (with empty values).

There are two lines of script code that also need to be include on any page that uses your Simplicity Block.

Endpoint

The SimplicityBlocks™ endpoint is a ready-to-use backend to capture data posted from forms in your widget or through AJAX POSTs. It provides universal capture of field data, honeypot SPAM protection, email notification, reporting, and data download capabilities. The endpoint to use is identified by the ID of your block.

Disable / Enable

If you do not plan on using the endpoint for your block, keep this set to disabled. Setting to enable will allow the enpoint to cature data POSTed to it.

Endpoint URL

Each block you create has a unique endpoint URL based on the ID of the block. This field lets you copy and paste the complete URL. PLEASE NOTE: Before a block is first saved the URL shown will contain 'BLOCKID' instead of the actual ID of theblock.

Honeypot Rule

A honeypot is a mechanism to help eliminated SPAM postings to an endpoint / form handler. It is typically a field that is hidden (via css) to the user and then either specifically left blank (because a bot will try to fill in all fields) or filled via script with a specific value. Sometimes a user will be asked to enter a value based on simple instructions. For example, enter the result of 2 + 3.

Based on the honeypot rule selected, the endpoint code checks the value of the honeypot field and makes a determination as to whether or not to consider the posted data valid or spam. If its is spam, the data is still captured but marked as spam.

The use of a honeypot is not mandatory with the endpoint, but it is recommended. If you do not wish to use the honeypot functionality keep the honeypot rule set to none. If you do wish to use the honepot rule you can choose from the following three options:

1. blank - this rule will verify that the field name you define as the honeypot is left blank.
2. number - this rule simply checks that the field name you define as the honeypot contains an integer value (i.e., all digits)
3. specify - this rule is used in conjunction with the honeypot valid values below which is a comma separated list of values that are valid. If the value found in the field name you define as the honeypot does not match one of those valid value, then it will be marked as spam.

Honeypot Field Name

The honeypot field name is simply the name you have chosen as the honeypot field. It is recommended that you select a name that looks link-secondary it would be a typical field name. For example, first_name. The enpoint code checks the value of this field against the rules you have set up to determine if the record should be flagged as spam or not.

Email Notification Address

If you wish to receive an email notification when a valid endpoint post is made (one not marked as spam), enter a single valid email address in this field. The email will come from support@simplicityblocks.com so you may want to make sure this address is whitelisted in your email.

Redirect URL (fully qualified)

Depending on your widget's functionality, you may want to redirect the user to another page after submitting to endpoint (e.g., if your widget is a form). The redirect URL is the fully qualified URL (i.e., it contains the https:// or http://) that the user will get redirected to after the submission.

If you want to pass an identifier to the endpoint that gets passed back to the redirect URL include a field named returnid in the POST submission to the endpoint. When the endpoint redirects back to another page it will include two URL paramaters:

• sbrid - this value will be the value of the returnid field you sent with the POST.
• sbepid - this is the request ID you can use to reference the specific endpoint request when viewing the data on the SimplicityBlocks site.

Honeypot Valid Values (used if honeypot rule = specify)

This field is only used if you set the honeypot rule to specify. Enter a list of valid values that the endpoint will check the value in the honeypot field against. Enter values separated by commas (no spaces).

How to POST Data to the Endpoint

The SimplicityBlocks™ endpoint is easy to use and automatically figures out field names that you send to it. Data automatically gets saved as a JSON object and is viewable and downloadable through the SimplicityBlocks™ block manager interface (shown later in this document).

If your widget is basically an HTML form you can simply change the form's action attribute to the endpoint URL for a particular block as shown here (replace 'BLOCKID' with your block ID):

  
    <form action="https://www.simplicityblocks.com/Endpoint/BLOCKID" method="POST">
  

If your widget is a single page application or other JavaScript application you can also use the fetch API to POST data as shown below. In this scenario you do not want to have a redirect URL set. When POSTING without a redirect URL the endpoint simply returns the ID of the request back as a string.

  
    fetch('https://www.simplicityblocks.com/Endpoint/BLOCKID', {
      method: 'POST',
      headers: {'Content-Type':'application/x-www-form-urlencoded'},
      body: 'fieldname1=fieldvalue1&fieldname2=fieldvalue2'
    });
  

Widget Communication with Host

The page hosting your SimplicityBlocks™ widget can communicate via attributes, the sendMessage method and events.

We have a separate page that describes and demonstrates the various ways to communicate with your widget. That page is here.

Block Statistics

Basic block statistics are available to show you the number of requests for a given data range as well as the source (page that the block is embedded in). The stats also show if the request was a valid request (invalid requests would be in those cases where you specified allowed domains and the request came from a domain that is not allowed). The RequestStatus will be 'OK' when the request is valid.

To view block statistics go the the Manage Blocks menu item. From the list of blocks that are showing click on the 'View Stats' link for the block you wish to view statistics for.

The page that shows the statistics defaults to the last month of data. You can change the date range, rows to display per page and you can choose whether to show only valid requests.

There is a link in the upper left hand corner of the stats view that also lets you view summary statistics for all of your blocks.

Endpoint Data

If you are utilizing an endpoint for one of you widgets, the data gets saved in key/value pairs based on the names of the fileds you submit to the endpoint. To view endpoint data go the the Manage Blocks menu item. From the list of blocks that are showing clock on the 'Endpoint POSTS' link for the block you wish to view data for.

Once you select a block's data to view the posts will show with a POST date, whether it was marked as SPAM, the Referer and the Honeypot Value. The listing defaults to the last month of data. To view more change the date range and click the Submit button. You can also choose whether or not you want to include requests marked as SPAM by selecting the checkbox.

For a specific request you can view the data by clicking on the 'View Data' link in the listing. This will display a dialog with the data for each field you POSTed.

Click on the X in the top right corner of the dialog to close it and go back to the list of POSTs.

From the list of endpoint requests you can also download the data to a csv file. Click on the 'Download CSV' button and your browser wiill show a save file dialog (Windows example shown here).

When you open the csv file (eaxample here shown using Microsoft Excel) the data will be shown as a column for each field you POSTed.

Getting Help

If you need help getting things working, send a support message at https://www.simplicityblocks.com/ManageBlocks/support