Table of Contents

minLevel	1
maxLevel	4

Direct ICS Integration

If you’re interested in setting up Ice Cream Social (ICS) on an online store, website or product that isn’t natively supported by our common integration methods, you’ve come to the right place!

A direct installation of ICS is needed for custom solutions and cases where advanced functionality or a specialized setups are called for. With minimal technical knowledge, access to the ICS admin and your site’s codebase, this guide will help you get ICS installed and running on your site in less than 10 minutes.

Tipexcerpt

hidden	true

A direct installation of ICS is needed for custom solutions and cases where advanced functionality or a specialized setups are called for. With minimal technical knowledge, access to the ICS admin and your site’s codebase, this guide will help you get ICS installed and running on your site in less than 10 minutes.

Panel

bgColor	#E3FCEF

Installing Ice Cream on a Shopify store? Check out https://ticketsocket.atlassian.net/wiki/pages/resumedraft.action?draftId=1965752394

Configuring the JavaScript code

1. ICS JS Code

Code Block

language	js

<script>
    window.onIcsLoaded = function() {
      ICS.init({
        version: 'latest',
        publicKey: 'REPLACE',
        campaignId: REPLACE',
        data: {
        	accountId: 'REPLACE',
        	email: REPLACE',
            name: REPLACE',
        	phoneNumber: 'REPLACE',
            orderId: 'REPLACE',
            revenue: 'REPLACE',
            transactionId: 'REPLACE'
      	},
        variables: {},
        theme: {},
        behavior: {
            type: 'referral',
            flavor: 'modal',
            openByDefault: true,
      	}
      });
  };

</script>
<script async defer crossorigin="anonymous" src="https://js.icecreamsocial.io/sdk.js" />

The JavaScript snippet above that will allow your ICS campaign to be displayed on your site in the form of a customizable widget. This code won’t work immediately out of the box so we’ll need to make a few tweaks to it before you install it on your site.

2. Finding and entering your campaign ID & public key

To get started, you’re first going to need to find have your campaign’s ID and your public key so you can add it into the script, this on hand. If you’re unsure where to find those, you can consult: Finding Your Campaign ID and Client Public Key

These two values is how ICS knows which campaign to load and grab the settings from.

Alternatively, you can see the campaign’s id in the URL of your browser’s address bar.

Image Removed

To find your public key, navigate to the Integrations section on the campaign page and open up the Post-Purchase Script modal.

Scroll until you get to line 25. The 32 character string is your public key.

Image Removed

Going back to the provided script now, replace these placeholder values with the appropriate ones you just identifiedEnter these values in the provided script , replacing the placeholder values.

Code Block

language	js

        publicKey: 'REPLACE',
        campaignId: 'REPLACE',

3. Configuring “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 variables in the data{} object to how you have them setup in your system.

Not all of the fields are required, but we recommend using as many as are available so ICS can collect the most data possible.

Once you’ve inputted your product’s variables correctly, the basic configuration of the ICS JS is completed!

ICS Data Variables

email -
Status
colour Red
title Required
Customer email
revenue -
Status
colour Yellow
title Required
* Total order value
transactionId -
Status
colour Yellow
title Required
* Transaction id from payment gateway
accountId - customer’s unique ID granted by your platform
name - Customer name
phoneNumber - Customer’s phone number
orderId - unique ID tied to customer’s order

*Revenue and transactionId are required for post-purchase campaigns, where rewards are issued through refunds on the customer’s original transaction

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:

Code Block

language	js

 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: parseFloat('{{order.subtotal_price | money_without_currency}}'.replaceAll(',','')),
            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:

Code Block

language	js

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

4. Including your configured ICS JS on your site

Now that you’ve configured the essentials, you can insert the resulting JavaScript into any pages you want the ICS widget to be present. Keep in mind, this code must be on any pages you want referrals to be tracked on for ICS to do its magic.

Put the code in any traditional place on your site, most commonly in the <head> or before closing the <body> tag on your site.

Further Customizations

By changing select attributes in the script, you can customize many aspects of it to suit your campaign, like when the widget is displayed, what it looks like or common tasks like to passing custom data into the widget. These options ensure that ICS will feel completely at home in your business’s website and is catered to your desired strategy.

Variables

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

ICS currently supports productName, productUrl and influencerName.

Variable

Description

Uses

Example

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!

Here’s an example of what the variables{} object looks like when configured:

Code Block

language	js

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

Behavior

Inside the script’s behavior{} object is where you’ll find options affecting the presentation of the widget as well as the type of widget to be used.

Code Block

language	js

        behavior: {
            type: 'referral',
            flavor: 'modal',
            openByDefault: true,
      	}

Variable

Description

Accepted values

type

Type determines which main behaviors the widget will be tracking

referral is the only option available currently

referral
More coming soon

flavor

Flavor controls how the widget is presented to the end user

modal - Widget is presented as a traditional modal, and a FAB to open it when it’s dismissed. This view is full screen on mobile devices and other small displays.
callout - Widget is presented as a smaller overlay and a FAB in the corner. This takes up much less real estate on desktop and doesn’t obscure the page’s content as much as the traditional modal but also demands less attention.

openByDefault

Determines when the widget will open

true - Widget will open and be presented to the user when the script loads
false - Widget won’t open on page load but instead when it is triggered through user action, like clicking a button or the FAB provided

Theme

The theme{} object accepts values that will change various visual attributes of the widget to tailor it to your company’s brand and identity.

Tip

More theme options coming soon

We’ve got plenty of options for customizing the widget’s appearance, but we’ve only

provided

basic options for now. If you’d like to change something that’s not included, please reach out to our team!

Colors

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

Variable

Description

"link"

Specifies color of links

"linkVisited

Specifies color of visited links

"bodyBg"

Specifies background color of the widget

"accent"

Specifies the color of important or interactive elements

"brand"

Specifies the color of certain elements

"ambient"

Specifies the color of the background of informative panels

Customized Colors Example

Code Block

language	json

 "colors": {
        "link": "#2C98FB",
        "linkVisited": "#5956D7",
        "bodyBg": "#F8F8F9",
        "accent": "#5956D7",
        "brand": "#2C98FB",
        "ambient": "#DDDDDD"
    },

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

"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

Code Block

language	json

  "borders": {
        "default": "1px solid",
        "style": "solid",
        "width": "1px",
        "radius": {
            "default": "16px",
            "none": "0"
        }

Loading the v1 widget with the v2 script

Our new script is backwards compatible so with a few adjustments to the code you can load Ice Cream Social’s v1 widget. This simplifies the installation of v1 as it no longer requires the addition of the cookie tracking script, which is incorporated instead in Ice Cream Social’s SDK.

The motivation behind supporting the v1 widget in the new script is to make the process of ultimately transitioning from using v1 to v2, once fully released, more seamless.

Two primary adjustments need to be made to the code snippet to support this:

Changing the line that specifies the version from version: 'latest' to version: 'v1'
Including addTransaction() function from the v1 integration script

After these changes are made, the resulting code will look like this (with some extraneous v2 lines removed for simplicity’s sake):

Code Block

language	js

<script>
    window.onIcsLoaded = function() {
      ICS.init({
        version: 'v1',
        publicKey: 'REPLACE',
        campaignId: 'REPLACE',
      });

  ics('addTransaction', {
    orderId: '{{order.order_number}}',
    email: '{{order.email}}',
    revenue: {{order.subtotal_price | money_without_currency}},
    name: '{{customer.name}}',
    inviteCookie: (document.cookie.match(/invite=([a-zA-Z0-9%]+)/) || [null] )[0],
    transactionId: '{{transactions[0].receipt.transaction_id}}',
    locale: 'sv-SE'
  });
  };

</script>
<script async defer crossorigin="anonymous" src="https://js.icecreamsocial.io/sdk.js" />

The values for the variables in the addTransaction() function should be changed to match how they will be used in your ICS integration.

Versions Compared

Old Version 12

New Version Current

Key

Direct ICS Integration

Configuring the JavaScript code

1. ICS JS Code

2. Finding and entering your campaign ID & public key

3. Configuring “Data” Object

ICS Data Variables

Shopify `data{}` Example

Square Online `data{}` Example

4. Including your configured ICS JS on your site

Further Customizations

Variables

Email Subject

Redirect URL

Email Subject

Behavior

Theme

More theme options coming soon

Colors

Customized Colors Example

Borders

Customize Borders Example

Loading the v1 widget with the v2 script

Page Comparison

Versions Compared

Old Version 12

New Version Current

Key

Direct ICS Integration

Configuring the JavaScript code

1. ICS JS Code

2. Finding and entering your campaign ID & public key

3. Configuring “Data” Object

ICS Data Variables

Shopify data{} Example

Square Online data{} Example

4. Including your configured ICS JS on your site

Further Customizations

Variables

Email Subject

Redirect URL

Email Subject

Behavior

Theme

More theme options coming soon

Colors

Customized Colors Example

Borders

Customize Borders Example

Loading the v1 widget with the v2 script

Shopify `data{}` Example

Square Online `data{}` Example