This module is only intended for internal use at TIDAL, but feel free to look at the code.
For the full specification, see the EventProducer specification.
Transportation layer (TL) - The part of event platform that is responsible for transporting events from the app to the backend.
The design uses a Job queue pattern for sending events, where each event is considered a job. As such, the design divides the functionality of sending an events into three major parts:
To keep the package from blocking the main thread we wrap it in a worker and use localforage with indexedDB as the driver.
Run pnpm i in the event-producer root folder.
pnpm test or pnpm test:ui
pnpm dev
import { init, sendEvent, bus } from '@tidal-music/event-producer';
import { credentialsProvider } from './credentialsProvider';
async function main() {
/**
* Bootstrap the event producer by calling the init function.
* This will start the scheduler and restore any previously stored events.
* Note must be called before dispatchEvent.
*/
await init({
appInfo: { appName: 'YourApp', appVersion: '1.2.3' },
// Used to initialize the blockedConsentCategories property
blockedConsentCategories: {
NECESSARY: false,
PERFORMANCE: false,
TARGETING: true,
},
// An access token provider, from @tidal-music/auth.
credentialsProvider,
// platform details
platform: {
browserName: 'Ice Hippo',
browserVersion: '1.2.3',
deviceVendor: 'Binocular',
model: 'shyPhone',
osName: 'Hov OS',
version: '1.2.3',
},
// Optional Debug for integration purposes. Checks if consentCategory is missing.
strictMode: false,
// URI identifying the TL Consumer ingest endpoint.
tlConsumerUri: '/api/event-batch',
// URI for unauthorized event batches.
tlPublicConsumerUri: '/api/public/event-batch',
});
// Now we can send events
sendEvent({
consentCategory: 'PERFORMANCE',
name: 'listened_to_track',
payload: {
certifiedBanger: true,
}
})
bus(()=>{
console.log('Event producer outage state changed', )
})
}
Queued events are only sent on the scheduler's interval, so events produced right before a user logs out can be left in the queue. If the credentials provider then throws because nobody is logged in, they stay there until the next login.
Call flush() before signing out or switching the active user to submit everything
that is queued while the current credentials are still available:
import { flush } from '@tidal-music/event-producer';
async function logout() {
// Waits for any sendEvent() calls still being prepared, then submits.
// Best effort: resolves when the queue is empty or a batch fails.
// Rejects only if no credentialsProvider is set or getCredentials() rejects.
await flush().catch(console.error);
// ...now swap the credentials provider / sign out
}
Notes:
flush() are still attributed to the user who produced them,
so it is safe for them to be sent later.tlPublicConsumerUri instead of stalling.flush() shares the in-flight submit with the scheduler: if a scheduled submit is
already running, flush() awaits that run rather than starting a second one.If the requirement is that no data from the outgoing user remains on the device,
pass { discardUnsent: true }. flush() still submits everything it can first;
whatever is left after that (for example because the network is down or nobody is
logged in any more) is dropped from memory and from IndexedDB, and the promise
resolves once the store is confirmed empty.
const { discarded } = await flush({ discardUnsent: true });
if (discarded > 0) {
console.warn(`${discarded} events could not be delivered and were discarded`);
}
Discarded events are lost for good, including playback events that count towards the user's listening history. Use this option only when the outgoing user's data must not remain on the device, i.e. signing out on a shared, public or otherwise untrusted device (kiosk, hotel TV, borrowed browser).
On a personal device prefer a plain flush(): leftover events are delivered on a
later run and stay attributed to the user who produced them. Never call
flush({ discardUnsent: true }) on a schedule, at startup, on token refresh or as
a general clean-up.