Skip to main content

How to Integrate with Alia's Client SDK

Learn how to send messages to Alia or listen for events using the client SDK to power dynamic, real-time experiences.

Rojen M Reji avatar
Written by Rojen M Reji
Updated today

You can use Alia's client SDK to send messages to or subscribe to events from Alia.

The client SDK exists by default on all Alia installations, so there's no setup or install needed as long as Alia is embedded.

Send messages to Alia

To send a message to Alia, you should first initialize Alia to an empty array if needed, as shown in the following code snippet:

window.alia = window.alia || []; 
window.alia.push(message);

This ensures that the message will be received even if sent before Alia loads.

Open a popup

To open a popup, send the following message:

window.alia = window.alia || [];
window.alia.push({
type: "open";
campaignID: number;
ignoreTargeting?: boolean | undefined;
})

You can find any campaign's ID in gray text next to the campaign name. For example, the campaign ID for the following campaign is 6:

The ignoreTargeting setting indicates whether the campaign's targeting settings should be respected. The behavior is as follows:

  • If true, the campaign will always appear regardless of whether targeting matches (as long as the campaign is live).

  • If false, the campaign will only appear if targeting matches when the open message is processed (not necessarily when sent).

  • If undefined or omitted, legacy behavior is used: the campaign will show if and only if targeting matched when the page loaded, regardless of whether it matches when the message is processed.

Close popup

To hide all Alia popups and other content, including any floating buttons, send the following message:

window.alia.push({ 
type: "close";
});

Subscribe to events from Alia

Alia fires CustomEvents with the prefix alia: whenever users interact with Alia popups. For example, the following code listens to sign up events:

document.addEventListener("alia:signup", (e) => {  
console.log(e.detail.email); // email provided in form submission
});

All events have a type property, which indicates the type of event, a date property, and a popupID property, which is the same ID as mentioned above. The rest of the object's shape depends on the type of event, as follows:

Popup view

Recorded when someone views a popup.

{ 
type: "popupView";
date: Date;
popupID: number;
campaignID: number;
campaignTitle: string;
}

Popup close

Recorded when someone closes a popup (either minimizing to a floating button, or closing the floating button).

{ 
type: "popupClose";
date: Date;
popupID: number;
campaignID: number;
campaignTitle: string;
}

Signup

Recorded when someone submits a form with their email or phone.

{ 
type: "signup";
date: Date;
popupID: number;
email: string | undefined;
phone: string | undefined;
campaignID: number;
campaignTitle: string;
}

Poll answered

Recorded when someone answers a survey question. answers will usually contain one element, unless the question is multiple choice.

{ 
type: "pollAnswered";
date: Date;
popupID: number;
answers: {
questionID: string;
questionText: string;
answerID: string | undefined;
answerText: string;
}[];
campaignID: number;
campaignTitle: string;
}

Reward claimed

Recorded when someone claims a reward (e.g. a discount or free shipping). rewardText is a human-readable description of the reward, such as "15% off".

{ 
type: "rewardClaimed";
date: Date;
popupID: number;
rewardID: number | undefined;
rewardText: string;
discountCode: string | undefined;
campaignID: number;
campaignTitle: string;
}
Did this answer your question?