Hybridge

A TypeScript library for seamless communication between web applications and native mobile applications.

Overview

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.

Features

• Event Bridging: Establish reliable communication channels between web and native applications
• Comprehensive Event System: Support for multiple event types:
  • Pageview events
  • Structured events
  • E-commerce events
  • A/B test events
  • And more
• Platform Integration: Built-in support for:
  • Google Analytics Data Layer
  • Firebase Analytics
  • Adjust
• Event Caching: Automatically caches events when the native bridge isn't immediately available
• Debug Mode: Easy debugging with console logging for development
• TypeScript Support: Full type definitions for all events and APIs

Installation

npm install hybridge
Copy

Quick Start

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 }
});
Copy

API Reference

Core Methods

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.

Event Methods

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.

Development

# 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
Copy

Architecture

Hybridge uses a modular architecture with these key components:

1. Core Bridge Module: Manages communication channels and event handling
2. Event Handlers: Process specific event types
3. Schema Definitions: Define type-safe interfaces for event data