Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Next »

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.

Login to the ICS admin and navigate to Campaigns.

Select the campaign you’re interested in and at the top of the page near its name, you’ll find the campaign’s unique id. Note this down.

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

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.

Going back to the provided script now, replace these placeholder values with the appropriate ones you just identified

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

  • No labels