A TypeScript library for seamless communication between web applications and native mobile applications.
Hybridge creates a communication channel between web applications and native contexts, allowing them to exchange events and data. It provides a structured event tracking system that handles various event types including pageviews, structured events, e-commerce events, and more.
fxt.webc.cro.hybridge (EU), set in terraform/locals.tfteam_id: ab, service_id: hybridge (terraform/tags.tf)Hybridge is not published to npm: CI has no publish job, and ADR-0001 distributes it as a static CDN file only. The hybridge package on the public npm registry is a different package. Web pages load the bundle with a script tag:
<script src="https://pulse.cro.flixbus.com/static/hybridge.js"></script>
The bundle is an IIFE that initialises itself on load (src/index.ts) and sets no global for the module API. The Quick Start below shows the module API of src/hybridge.ts as used inside this repository.
import hybridge from 'hybridge';
// Optional: Enable debug mode
hybridge.setDebug(true);
// Initialize the bridge
hybridge.init();
// Track a pageview
hybridge.sendPageviewEvent('/search-results');
// Track a structured event
hybridge.sendStructuredEvent({
category: 'User Interactions',
action: 'button.click',
label: 'Submit Button'
});
// Track an e-commerce event
hybridge.sendEcomEvent({
action: 'purchase',
products: [{ id: 'product-123', name: 'Sample Product', price: 19.99 }],
transaction: { id: 'tx-456', revenue: 19.99 }
});
hybridge.init()Initializes the bridge between web and native applications.
hybridge.setDebug(value: boolean)Enables or disables debug mode which logs events to the console.
hybridge.setPort(value: MessagePort)Manually sets the communication port.
hybridge.sendPageviewEvent(url: string)Tracks page navigation events.
hybridge.sendStructuredEvent(payloads: StructuredEvent['payloads'])Tracks structured events with categories and actions.
hybridge.sendEcomEvent(payloads: EcomEvent['payloads'])Tracks e-commerce events like purchases, product views, etc.
hybridge.sendAbEvent(payloads: AbtestEvent['payloads'])Tracks A/B test variants.
hybridge.sendAdjustEvent(payloads: AdjustEvent['payloads'])Sends events to the Adjust mobile attribution platform.
hybridge.sendFirebaseEvent(payloads: FirebaseEvent['payloads'])Sends events to Firebase Analytics.
hybridge.sendDatalayerEvent(payloads: DLStructured['payloads'])Pushes events to Google Analytics data layer.
# Build for production
npm run build
# Build for development (with source maps)
npm run build:dev
# Format code
npm run format
# Lint code
npm run lint
# Generate documentation
npm run doc
# run tests
npm run test:coverage
Hybridge uses a modular architecture with these key components:
For a detailed architecture diagram and system context, see docs/architecture.md.
Architecture decision records are stored in docs/adr/.
GitLab CI (.gitlab-ci.yml) builds dist/hybridge.js with esbuild and uploads it to S3 behind CloudFront. There is no npm publish job.
| Job | Runs on | Serves | Cache-Control |
|---|---|---|---|
deploy-dev |
every pipeline | https://pulse.cro-dev.flixbus.com/static/hybridge.js |
max-age=0,public |
deploy-prod |
master |
https://pulse.cro.flixbus.com/static/hybridge.js |
max-age=600,public |
Both jobs invalidate their CloudFront distribution (/*) after the upload. docs-dev and docs-prod publish the TypeDoc output the same way, and upload-sourcemaps-prod uploads the source maps to Datadog under service:fxt.monolith.shop. test:coverage has allow_failure: true, so a failing test run does not stop the deploy jobs. Rollback steps are in the runbook.
| SLO | Target | Source of truth |
|---|---|---|
| [SplitHappens] Hybridge CDN file availability | 99.5% over 30 days | Hybridge - SLO |
The SLO and its synthetic test CRO Hybridge: CDN file reachable are defined in terraform/slos.tf. Alerts are listed in the runbook.
https://pulse.cro.flixbus.com/static/hybridge.js