feat: Expose onShoppableAdsReady on RoktManager

[zach-will]

Background

As part of embedding the Rokt Thank You Element (TYE) into the Joint SDK, we need a way for partners to register callbacks and listen to TYE events.

Previously, partners were instructed to attach event listeners inside the TYE onLoad handler:

script.src = baseUrl + '/rokt-thank-you-element.js'
script.onLoad = () => {
  window.RoktThankYouElement.on('THANK_YOU_ELEMENT_LOADING_INITIATED').subscribe(() => {
    // Do something
  });
}

With TYE now internalized within the Joint SDK, this approach is no longer viable.

We also want to allow partners to register event listeners before mParticle or RoktKit is fully ready. To support this, we’ve introduced a new method, onShoppableAdsReady, which exposes a safe hook for registering TYE event listeners.

The updated integration pattern is:

  window.mParticle.Rokt.onShoppableAdsReady(() => {
    window.RoktThankYouElement.on('THANK_YOU_ELEMENT_LOADING_INITIATED').subscribe(() => {
      // Do something
    });
  });
  window.mParticle?.ready?.(() => {

Changes to snippet js.

Integrations will now require onShoppableAdsReady to be included in the RoktMethods stub:

[
      'selectPlacements',
      'hashAttributes',
      'setExtensionData',
      'use',
      'onShoppableAdsReady',
    ].forEach(
    (name) => {
      window.mParticle.Rokt[name] = (...args: any[]) =>
        window.mParticle.config.rq.push([`Rokt.${name}`, ...args])
    },
  )

What Changed

• Added a new public method: onShoppableAdsReady in RoktManager
• When ThankYouElement is included in the kit config:
  • RoktKit is initialized early via RoktManager, but is not marked as ready until the launcher is defined
  • Just before loading rokt-thank-you-element.js, the onShoppableAdsReady callback queue in RoktManager is flushed
    • This ensures all queued callbacks are registered as onLoad handlers
    • Any subsequent calls to onShoppableAdsReady are executed immediately (no longer deferred)

Deployment order

• Deploy this PR
• Deploy changes to RoktKit: PR-91

Media

Screen.Recording.2026-04-27.at.9.53.49.AM.mov

[cursor]

PR Summary

Medium Risk
Introduces a new public API and new message-queue flushing path in RoktManager, which could affect initialization order and deferred-call behavior if misused or if the kit never flushes the queue.

Overview
Exposes a new mParticle.Rokt.onShoppableAdsReady callback registration API, including snippet stubs in snippet.js and snippet.rokt.js so calls can be made before the full SDK loads.

Updates RoktManager/IRoktKit to support deferring onShoppableAdsReady registrations until shoppable ads are explicitly marked as loaded, then flushes only those queued callbacks via flushOnShoppableAdsReadyMessageQueue and executes subsequent registrations immediately. Adds comprehensive Jest coverage for queuing, flushing semantics, and error logging when callback registration fails.

^{Reviewed by Cursor Bugbot for commit e04b3f4. Bugbot is set up for automated code reviews on this repo. Configure here.}

[sonarqubecloud]

Quality Gate failed

Failed conditions
23.3% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

[mparticle-automation]

🎉 This PR is included in version 2.66.0 🎉

The release is available on:

• v2.66.0
• GitHub release

Your semantic-release bot 📦🚀