Direct JavaScript Integration (Beta Widget)
- bryan bykowicz
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 Shopify Setup Guide (Beta Widget)
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 have your campaign’s ID and your public key 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.
Enter these values in the provided script , replacing the placeholder values.
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 emailrevenue- Required* Total order valuetransactionId- Required* Transaction id from payment gatewayaccountId- customer’s unique ID granted by your platformname- Customer namephoneNumber- Customer’s phone numberorderId- 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:
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 |
|---|---|---|---|
| The item the customer has purchased | Replaces | Email SubjectYour friend |
| The URL slug of the product that people will be redirected to when they click on an invite
| Replaces
| Redirect URLhttps://www.yourstore.com/products/ |
| The customer’s name. It can be a full name, first name, last name, or even an alias. The choice is yours. | Replaces
| Email SubjectYour friend |
Here’s an example of what the variables{} object looks like when configured:
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.
Variable | Description | Accepted values |
|---|---|---|
| Type determines which main behaviors the widget will be tracking
|
|
| Flavor controls how the widget is presented to the end user |
|
| Determines when the widget will open |
|