1 Overview
- 1.1 Initialize Function
  - 1.1.1 Attributes
- 1.2 Data{} Object
  - 1.2.1 Attributes
  - 1.2.2 Shopify data{} Example
  - 1.2.3 Square Online data{} Example
- 1.3 Variables{} Object
  - 1.3.1 Attributes
  - 1.3.2 Code Example
- 1.4 Theme{} Object
  - 1.4.1 Attributes
    - 1.4.1.1 Colors{}
      - 1.4.1.1.1 Customized Colors Example
    - 1.4.1.2 Borders{}
      - 1.4.1.2.1 Customize Borders Example
- 1.5 Behavior{} Object
  - 1.5.1 Attributes
- 1.6 URI Source

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 values

Name	Description	Format	Required	Accepted values
`behavior{}`	controls what the user sees and when and where they see it	Object	REQUIRED	`allowedURLs` `blockedURLs` `currency` `delay` `flavor` `forceOpen` `mountSelector` View details
`campaignId`	A unique number assigned to each ICS campaign	String	REQUIRED	Client campaign ID Finding your campaign ID and public key
`data{}`	Data passed to the widget for attribution	DataLayer Object	REQUIRED	`accountId` `email` `engagement` `invite` `name` `orderId` `phoneNumber` `subtotal` `transactionId` View details
`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 Finding your campaign ID and public key
`theme{}`	Provides options for applying custom themes to the widget	Object	oPTIONAL	View details
`variables{}`	Optional variables to be replaced in the widget	Object	oPTIONAL	`productName` `productUrl` `influencerName` View details
`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

Name	Description	Format	Required	Accepted values
`accountId`	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
`email`	Passing email allows user to bypass the email entry step if the client's GDPR settings allow	String	Optional	Any email
`engagement`	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

Shopify `data{}` Example

If you were using Shopify, you’d change the variables to their Shopify specific equivalents so ICS can capture the correct info, the result would look like this:

 data: {
        	accountId: '{{checkout.customer.id}}',
        	email: '{{checkout.email}}',
            name: '{{checkout.customer.first_name}} {{checkout.customer.last_name}}',
        	phoneNumber: '{{checkout.customer.phone}}',
            orderId: '{{checkout.order_number}}',
            revenue: '{{ checkout.line_items_subtotal_price | money_without_currency }}',
            transactionId: '{{transactions[0].receipt.transaction_id}}'
        }

Square Online `data{}` Example

Most variables are not standardized and are platform specified. For example, Square Online’s syntax is much different than Shopify’s:

 data: {
        	email: '{email}',
            name: '{name}',
            orderId: '{orderid}',
            revenue: '{total}',
            transactionId: '{txid}'
        }

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.

Attributes

Name	Description	Uses	Examples

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!

Code Example

An example of what the variables{} object might look like when configured:

        variables: {
            productName: '{item}',
            productUrl: '{itemURL}',
            influencerName: '{customerName}'
      	}

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.

Attributes

Colors{}

Give your widget a splash of personality by setting custom color values. Color variables accept hex codes, RGB and HSL values.

Variable	Description

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

Customized Colors Example

Borders{}

Adjusting your border styles can make the difference between an approachable, bubbly widget and a impeccably neat and dignified widget, each demanding attention in their own way!

Variable	Description

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

Customize Borders Example

Behavior{} Object

Attributes

Name	Description	Format	Required	Accepted values

Name	Description	Format	Required	Accepted values
`allowedURLs`	Only show the widget and collect data on these specified pages	Array	Optional	One or more URLs
`blockedURLs`	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	List of supported locales
`delay`	Amount of time in ms before the widget will be shown. If `openByDefault` = false, delay will be ignored	Number	Optional	Any number
`flavor`	Flavor controls how the widget appears and will be presented to the end user		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	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	`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	Boolean	Optional	`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.	String	REQUIRED	`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.

ICS Beta Widget Reference

Anatomy of the Integration Script

Overview

Initialize Function

Attributes

Data{} Object

Attributes

Shopify `data{}` Example

Square Online `data{}` Example

Variables{} Object

Attributes

Code Example

Theme{} Object

Attributes

Colors{}

Customized Colors Example

Borders{}

Customize Borders Example

Behavior{} Object

Attributes

URI Source

Anatomy of the Integration Script

Overview

Initialize Function

Attributes

Data{} Object

Attributes

Shopify data{} Example

Square Online data{} Example

Variables{} Object

Attributes

Code Example

Theme{} Object

Attributes

Colors{}

Customized Colors Example

Borders{}

Customize Borders Example

Behavior{} Object

Attributes

URI Source

Shopify `data{}` Example

Square Online `data{}` Example