In-App Message JavaScript Bridge

All methods covered in this document are JavaScript APIs available only in HTML-based in-app messages.

JavaScript Bridge is a tool for the HTML in-app message and Hackle's SDK to interact with each other.

• When a close button is clicked

• When navigating to a link

• When an action corresponding to a campaign conversion is performed

• When a Hackle feature call is needed within the in-app message

In these situations, you can use JavaScript Bridge to control user behavior tracking, URL navigation, and in-app message display.

hackleBridgeReady

When Hackle.bridge becomes available in the HTML, the hackleBridgeReady event is published. It is recommended to access Hackle.bridge inside the callback of that event listener.

Access to Hackle.bridge must always occur after the Ready event has been fired.

Example

<button id="hackle-url">
	Go to Hackle
</button>
<script>
  window.addEventListener("hackleBridgeReady", function(){
    document.querySelector("#hackle-url").addEventListener("click", function(e) {
      Hackle.bridge.openUrl("https://hackle.io");
    });
	})
</script>

Opening a URL

Opens the URL in the browser of the device where the in-app message is displayed and closes the in-app message.

• Supports deep links.

• Does not track click events.

Hackle.bridge.openUrl(url: string): void
Hackle.bridge.openUrl(url: HackleInAppMessageLink): void

interface HackleInAppMessageLink {
  url: string
  target: "CURRENT" | "NEW_TAB" | "NEW_WINDOW"
  shouldCloseAfterLink: boolean
}

target	Description
CURRENT	Open in the current page
NEW_TAB	Open in a new tab
NEW_WINDOW	Open in a new window

Apps (Android, iOS, Flutter, React Native) support only CURRENT.

Example

Opens the URL in the current page and closes the in-app message.

<button id="hackle-url">
	Go to Hackle
</button>
<script>
  window.addEventListener("hackleBridgeReady", function(){
    document.querySelector("#hackle-url").addEventListener("click", function(e) {
      Hackle.bridge.openUrl("https://hackle.io");
    });
	})
</script>

Open in new tab and close in-app message

<button id="hackle-url">
	Go to Hackle
</button>
<script>
  window.addEventListener("hackleBridgeReady", function(){
    document.querySelector("#hackle-url").addEventListener("click", function(e) {
      Hackle.bridge.openUrl({
        url: "https://hackle.io",
        target: "NEW_TAB",
				shouldCloseAfterLink: true
 			});
    });
	})
</script>

Open in new window and close in-app message

<button id="hackle-url">
	Go to Hackle
</button>
<script>
  window.addEventListener("hackleBridgeReady", function(){
    document.querySelector("#hackle-url").addEventListener("click", function(e) {
      Hackle.bridge.openUrl({
        url: "https://hackle.io",
        target: "NEW_WINDOW",
				shouldCloseAfterLink: true
 			});
    });
	})
</script>

Personalization

In in-app message HTML, you can display personalized messages using user information and event information.

Querying User Properties

Queries the properties of the user that triggered the message.

Hackle.bridge.getUser(): User

Example

const user = Hackle.bridge.getUser();
const props = user?.properties ?? {};
const age = props["age"] ?? -1;

if (age > 20) {
  document.getElementById("new-year-text").textContent 
    = `A special deal exclusively for you, turning ${age} in the new year!`;
}

Querying the Trigger Event

Queries the information of the event that triggered the in-app message. It includes the event key, value, and the full list of properties.

Hackle.bridge.getTriggerEvent(): HackleEvent | undefined

Example

const event = Hackle.bridge.getTriggerEvent();
const promoDate = event?.properties?.["promo_date"] ?? "11.29";
document.getElementById("period-text").textContent = promoDate + " FRI — Special sale until midnight";

Querying a Trigger Event Property

Queries a single property of the event that triggered the in-app message.

Hackle.bridge.getTriggerEventProperty(
    key: String, 
    defaultValue: string | number | boolean | Array<string | number>
): PropertyValue

Example

const promoDate = Hackle.bridge.getTriggerEventProperty("promo_date", "11.29");
document.getElementById("period-text").textContent = promoDate + " FRI — Special sale until midnight";

User Behavior Tracking

Tracking Clicks

You can track click events corresponding to conversions in an in-app message campaign.

The $in_app_action event is triggered, and based on this event, you can check campaign performance in the Hackle Dashboard.

• View performance measurement in detail

• View in-app message events in detail

trackClick(elementId?: string): void

Example

<button id="hackle-conversion">
	Hackle Conversion
</button>
<script>
  window.addEventListener("hackleBridgeReady", function(){
    document.querySelector("#hackle-conversion").addEventListener("click", function(e) {
      Hackle.bridge.trackClick("main-funnel-user-conversion-1");
    });
	})
</script>

elementId added as $in_app_action event property

Handling link click and click tracking simultaneously

When a link click itself is considered a conversion, handle opening the URL and collecting the link click event simultaneously.

handleUrl(url: string | HackleInAppMessageLink, elementId?: string): void

Example

<button id="hackle-link">
	Hackle Link
</button>
<script>
  window.addEventListener("hackleBridgeReady", function(){
    document.querySelector("#hackle-link").addEventListener("click", function(e) {
      Hackle.bridge.handleUrl("https://hackle.io","main-funnel-user-conversion-1");
    });
	})
</script>

Event Tracking

Sends an event. Same as the method for sending events in the JavaScript SDK.

Example

<button id="custom-btn">X</button>
<script>
  window.addEventListener("hackleBridgeReady", () => {
    const closeButton = document.querySelector("#custom-btn");

    const event = {
      key: "purchase",
      properties: {
        pay_method: "CARD",
        discount_amount: 800,
        is_discount: true
      }
    };

    closeButton.addEventListener("click", () => {
      Hackle.bridge.track(event);
    });
})
</script>

Closing an In-App Message

Closes the in-app message.

closeInAppMessage(hideDuration?: boolean | number): void

hideDuration	Description
true	Hide for one day
false	Close immediately
number	Hide for the number of minutes passed
null / undefined	Close immediately

Example

<button id="close-btn">X</button>
<button id="hide-today-btn">Do not show today</button>
<button id="hide-10m-btn">Do not show for 10 minutes</button>

<script>
  window.addEventListener("hackleBridgeReady", () => {
    const closeButton = document.querySelector("#close-btn");
    const hideTodayButton = document.querySelector("#hide-today-btn");
    const hide10mButton = document.querySelector("#hide-10m-btn");

    closeButton.addEventListener("click", () => {
      Hackle.bridge.closeInAppMessage();
    });

    hideTodayButton.addEventListener("click", () => {
      Hackle.bridge.closeInAppMessage(true);
    });

    hide10mButton.addEventListener("click", () => {
      Hackle.bridge.closeInAppMessage(10);
    });
  });
</script>

Get started quickly with the HTML in-app message template.

We provide HTML In-App Message Templates that you can use immediately with copy-paste.