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.

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

<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 your campaign’s ID and your public key so you can add it into the script, this is how ICS knows which campaign to load and grab the settings from.

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 - REQUIRED Customer email
revenue - REQUIRED* Total order value
transactionId - 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:

 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:

 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:

        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.

        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

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):

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

Direct JavaScript Integration V2 Widget

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

Loading the v1 widget with the v2 script

Shopify `data{}` Example

Square Online `data{}` Example