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

NameDescriptionFormatRequired

Accepted

behavior{}

controls what the user sees and when and where they see it


Object


Required


  • allowedURLs

  • blockedURLs

  • currency

  • delay

  • flavor

  • forceOpen

  • mountSelector


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


  • accountId

  • email

  • engagement

  • invite

  • name

  • orderId

  • phoneNumber

  • subtotal

  • transactionId


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


List of supported locales


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


See theme{} section


variables{}

Optional variables to be replaced in the widget


Object


Optional


  • productName

  • productUrl

  • influencerName


version

The version of the widget to use. If unspecified, this defaults to ‘latest’

String


Optional


  • 'latest'

  • 'v1'


 

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


OptionalAny
email

Passing email allows user to bypass the email entry step if the client's GDPR settings allow


String


OptionalAny email
enagement

If no engagement is passed, the widget will automatically detect engagement type based on the following conditions:

  • orderId is passed and there is a subtotal -> transaction

  • orderId is NOT passed and there is NOT a subtotal -> participation

  • customer sees the widget when it is loaded for the first time -> pageview

If you would like to record a signup, or explicitly set a specific engagement, pass it here.


String


Optional
  • transaction

  • participation

  • signup

  • pageview 


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
  • Transaction id from payment gateway

  • only required  Used to verify order and issue rewards/refunds

  • Used for post-purchase campaigns 


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 {{product.name}} in email subject and share message in the campaign settings


Email Subject

Your friend {{influencer.name}} just sent you a deal for {{product.name}}!


productUrl

The URL slug of the product that people will be redirected to when they click on an invite


Replaces {{product.url}} in Redirect URL in the campaign settings.

 



Redirect URL

https://www.yourstore.com/products/{{product.url}}

influencerName

The customer’s name. It can be a full name, first name, last name, or even an alias. The choice is yours.


Replaces {{influencer.name}} in Email Subject and Share Message in the Campaign settings



Email Subject

Your friend {{influencer.name}} just sent you a deal!


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


blockerUrlsShow and collect data on all pages except these specified pagesArray

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


List of supported locales


delayAmount of time in ms before the widget will be shown. If openByDefault = false, delay will be ignoredNumber

Optional


Any number (in ms)
flavor

Flavor controls how the widget appears and will be presented to the end user


String

Required


  • modal - Widget is presented as a traditional modal that’s full screen on mobile devices and small displays

  • callout - Widget is presented as a smaller, popover overlay. takes up much less screen real estate and doesn’t obscure the page’s content, though demands less attention as a traditional modal

  • embedded - allows you to embed a widget directly in a webpage. the placement is determined by the mountSelector field


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


  • true - the widget will open each time the user lands on an ICS-scripted page

  • false - widget won’t open automatically each time and instead will respect the openByDefault setting


mountSelector

CSS selector for where the iframe should be mounted


StringRequired 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. 


BooleanOptional
  • true - the widget will open automatically the first time the user lands on an ICS-scripted page

  • false - the widget will only open when initiated by a user


requestPhoneNumber

Whether or not the user's phone number should be requested by the widget


BooleanOptional
  • true - Influencer’s phone number will be requested

  • false - Influencer’s phone number won’t be requested


type

Type determines which widget is to be used. referral is the only option currently available.


StringRequired  
  • referral

  • More coming soon


 

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.