Overview
The ICS integration script is your gateway to installing ICS widgets and tools your site. The script takes in a host of options and settings, communicates those to the ICS JS SDK and API which in turn returns appropriately configured content. Installing this script is the primary way that ICS is integrated on client pages.
This article breaks down the main pieces of this script, describes their purpose and provides a reference that includes supported variables and their accepted inputs.
Initialize Function
The ICS.init() function is a key component to running the ICS app. Essentially it tells the widget to initialize with the configuration data provided.
It contains many variables like which version of the widget should be loaded, which campaign to pull assets from and even what language should be used. Beyond that, it includes a handful of objects like data, variables, and theme which provide organized sets of options used to tweak and configure the widget.
Attributes
| Name | Description | Format | Required | Accepted |
| behavior{} | controls what the user sees and when and where they see it | Object | Required |
|
| campaignId | A unique number assigned to each ICS campaign | String | Required | Client campaign ID |
| data{} | Data passed to the widget for attribution | DataLayer Object | Required |
|
| locale | Determines the locale to used for the widget content and display. Defaults to browser language but can be set in the admin or specified directly in the script. | String | Optional | |
| publicKey | A 32-character alphanumeric string unique to each ICS client | String | Required | Client public key |
| theme{} | Provides options for applying custom themes to the widget | Object | Optional | |
| variables{} | Optional variables to be replaced in the widget | Object | Optional |
|
| version | The version of the widget to use. If unspecified, this defaults to ‘latest’ | String | Optional |
|
Data{} Object
For the ICS widget to create and track influencers and referrals, certain pieces of data need to be fed to the script. To do this, you’ll have to map the attributes in the data{} object to the equivalent values used in your system.
Not all of the fields are required, but we recommend using as many as your data usage policies allow so ICS can collect the most data possible for you.
Attributes
Name | Description | Format | Required | Accepted Values |
acountId | Customer’s unique ID granted by your platform. Used if you would like to tie the influencer account to their account in your system | String | Optional | Any |
Passing email allows user to bypass the email entry step if the client's GDPR settings allow | String | Optional | Any email | |
| enagement | If no engagement is passed, the widget will automatically detect engagement type based on the following conditions:
If you would like to record a signup, or explicitly set a specific engagement, pass it here. | String | Optional |
|
| invite | The invite id for conversion attribution. Populated automatically when a customer was invited.. | String | Optional | Invite id number |
| name | Influencer’s name | String | Optional | Any |
| orderId | Unique ID tied to an influencer’s order | String | Required if subtotal is > 0 | Any |
| phoneNumber | Customer’s phone number to be used for SMS notifications | String | Required if email not provided | Any phone number |
| subtotal | If tracking influencer order total | String | Required for post-purchase campaigns | Any number |
| transactionId |
| String | Required if subtotal is > 0 | Any |
Variables{} Object
The variables{} object allows for mapping dynamic variables which are used to collect and display various pieces of data captured by the script. The corresponding dynamic tag, e.g. {{variableName}}, can be used in offer text, emails and other notifications to be replaced with the captured values. Variables and dynamics tags can be a powerful tool in making your content and correspondences feel personalized and unique for the end user.
Note that any values like this passed into the script will take precedence over any variables set in the admin.
ICS currently supports productName, productUrl and influencerName, but more values will become available later.
Name | Description | Uses | Examples |
| productName | The item the customer has purchased | Replaces | Email Subject Your friend |
| productUrl | The URL slug of the product that people will be redirected to when they click on an invite | Replaces
| Redirect URL https://www.yourstore.com/products/ |
| influencerName | The customer’s name. It can be a full name, first name, last name, or even an alias. The choice is yours. | Replaces | Email Subject Your friend |
Theme{} Object
The theme{} object accepts values that will change various visual attributes of the widget to tailor it to your company’s brand and identity
Colors{}
Give your widget a splash of personality by setting custom color values. Color variables accept hex codes, RGB and HSL values.
Variable | Description |
| "accent" | Specifies the color of certain elements |
| "ambient" | Specifies the color of the background of informative panels |
| "bodyBg" | Specifies background color of the widget |
| "brand" | Specifies the color of important or interactive elements |
| "link" | Specifies color of links |
| "linkVisited" | Specifies color of visited links |
Borders{}
Adjusting your border styles can result in an approachable, bubbly widget or an impeccably neat and dignified widget, each demanding attention in their own way
Variable | Description |
| "default" | Determines the default border styles |
| "style" | Determines what kind of border to display |
| "width" | Determines the width of the borders |
| "radius":{} | |
| "default" | Determines the “roundness” of borders |
Behavior{} Object
Name | Description | Format | Required | Accepted values |
| allowedUrls | Only show the widget and collect data on these specified pages | Array | Optional | One or more URLs |
| blockerUrls | Show and collect data on all pages except these specified pages | Array | Optional | One or more URLs |
| currency | This will will default to the currency symbol of the provided locale. If provided, will override the currency, regardless of locale | String | Optional | |
| delay | Amount of time in ms before the widget will be shown. If openByDefault = false, delay will be ignored | Number | Optional | Any number (in ms) |
| flavor | Flavor controls how the widget appears and will be presented to the end user | String | Required |
|
| forceOpen | Forces the widget to be open. Does not respect if the user dismissed the widget or not and will open every time. This is useful on post-purchase confirmation pages but generally should be used sparingly to avoid user annoyance. | Boolean | Optional |
|
| mountSelector | CSS selector for where the iframe should be mounted | String | Required when using embedded flavor | CSS selector |
| openByDefault | Determines when the widget will open. If the user has dismissed the widget previously it won’t open again automatically on subsequent page loads to avoid hindering general site navigation. | Boolean | Optional |
|
| requestPhoneNumber | Whether or not the user's phone number should be requested by the widget | Boolean | Optional |
|
| type | Type determines which widget is to be used. | String | Required |
|
URI Source
This line of the script includes the URI of Ice Cream Social’s SDK, where all the external assets, resources and logic for the application are stored and then referenced by the integration script.