hybridge

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

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

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

Architecture

Hybridge uses a modular architecture with these key components:

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