@openpack/app-bridge

Die App Bridge ermöglicht eine sichere, promise-basierte Kommunikation zwischen der openpack Platform und deiner Anwendung, die innerhalb eines IFrames läuft.

Es basiert auf Penpal und bietet eine typsichere Abstraktionsebene für die postMessage-Kommunikation.

Features

• Typsicherheit: Volle TypeScript-Unterstützung für alle Kommunikationswege.
• Promise-basiert: Keine manuellen Event-Listener für postMessage nötig.
• Framework-agnostisch: Funktioniert mit React, Vue, Angular oder Vanilla JS.
• Leichtgewichtig: Minimaler Footprint durch Penpal-Basis.

Installation

npm i @openpack/app-bridge

Verwendung in JavaScript / TypeScript

Die AppBridge Klasse stellt die Verbindung zur Platform her. Da sie promise-basiert ist, kannst du sie einfach in jeder JavaScript-Umgebung nutzen.

import { AppBridge } from '@openpack/app-bridge';

// 1. AppBridge initialisieren
const appBridge = new AppBridge({
  allowedOrigins: ['*'], // In Produktion restriktiver sein
});

// 2. Verbindung aufbauen
const connection = appBridge.connect();

// 3. Auf Verbindung warten und Methoden nutzen
connection.promise
  .then(async (platform) => {
    console.log('Verbunden mit openpack Platform');

    // Beispiel: Nutzerdaten abrufen
    const user = await platform.getUser();
    console.log(`Hallo, ${user.firstName} ${user.lastName}!`);

    // Beispiel: Benachrichtigung senden
    await platform.notify({
      message: 'Erfolgreich verbunden!',
      type: 'success'
    });

    // Beispiel: Token abrufen
    const token = await platform.getAccessToken();
    console.log('Access Token:', token);
  })
  .catch((err) => {
    console.error('Verbindungsfehler:', err);
  });

Verwendung in React

Für React-Anwendungen empfehlen wir die Nutzung eines React Contexts. Dadurch wird die Verbindung einmalig aufgebaut und der Verbindungsstatus sowie die Platform-Methoden stehen in der gesamten App über einen Hook zur Verfügung.

1. Provider erstellen (AppBridgeContext.tsx)

Erstelle einen Context, der die Initialisierung der AppBridge übernimmt und den Lade- sowie Fehlerzustand verwaltet.

import { AppBridge, type PlatformMethods } from '@openpack/app-bridge';
import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';

interface AppBridgeContextType {
  appBridge: AppBridge;
  openpackPlatform: PlatformMethods;
}

const AppBridgeContext = createContext<AppBridgeContextType | null>(null);

export function useAppBridge() {
  const context = useContext(AppBridgeContext);
  if (!context) {
    throw new Error('useAppBridge must be used within an AppBridgeProvider');
  }
  return context;
}

export function AppBridgeProvider({ children }: { children: ReactNode }) {
  const [state, setState] = useState<AppBridgeContextType | null>(null);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    let isMounted = true;

    // Origin dynamisch aus dem Referrer auslesen oder spezifisch setzen
    const allowedOrigins = document.referrer ? [new URL(document.referrer).origin] : ['*'];

    const appBridge = new AppBridge({ allowedOrigins });
    const connection = appBridge.connect();

    connection.promise
      .then((openpackPlatform) => {
        if (isMounted) setState({ appBridge, openpackPlatform });
      })
      .catch((err) => {
        if (isMounted) {
          console.error('Failed to connect to platform:', err);
          setError(err instanceof Error ? err : new Error(String(err)));
        }
      });

    return () => {
      isMounted = false;
    };
  }, []);

  if (error) {
    return <div>Connection Error: {error.message}</div>;
  }

  if (!state) {
    return <div>Connecting to platform...</div>;
  }

  return (
    <AppBridgeContext.Provider value={state}>
      {children}
    </AppBridgeContext.Provider>
  );
}

2. App mit dem Provider wrappen (main.tsx)

Binde den Provider ganz oben in deiner Anwendung ein. Alle Children (wie App) werden erst gerendert, wenn die Verbindung zur Plattform erfolgreich hergestellt wurde.

import React from 'react';
import { createRoot } from 'react-dom/client';
import { AppBridgeProvider } from './AppBridgeContext';
import { App } from './App';

const container = document.getElementById('root');

if (container) {
  const root = createRoot(container);
  
  root.render(
    <React.StrictMode>
      <AppBridgeProvider>
        <App />
      </AppBridgeProvider>
    </React.StrictMode>
  );
}

3. Nutzung in Komponenten (App.tsx)

Nutze einfach den useAppBridge Hook in deinen Komponenten. Da der Provider das Rendern verzögert, bis die Verbindung steht, kannst du dir sicher sein, dass openpackPlatform immer verfügbar ist.

import { useEffect, useState } from 'react';
import { useAppBridge } from './AppBridgeContext';
import type { UserInfo } from '@openpack/app-bridge';

export const App = () => {
  // Zugriff auf die Platform-Methoden über den Hook
  const { openpackPlatform } = useAppBridge();
  const [userInfo, setUserInfo] = useState<UserInfo | null>(null);

  useEffect(() => {
    const loadData = async () => {
      try {
        const user = await openpackPlatform.getUser();
        setUserInfo(user);
      } catch (err) {
        console.error('Fehler beim Laden:', err);
      }
    };

    loadData();
  }, [openpackPlatform]);

  const handleAction = async () => {
    try {
      const token = await openpackPlatform.getAccessToken();
      console.log('Token:', token);

      await openpackPlatform.notify({ 
        message: 'Aktion erfolgreich!', 
        type: 'success' 
      });
    } catch (err) {
      console.error('Fehler:', err);
    }
  };

  return (
    <div>
      <h1>Meine Anwendung</h1>
      {userInfo ? (
        <p>Hallo, {userInfo.firstName}!</p>
      ) : (
        <p>Lade Nutzerdaten...</p>
      )}

      <button onClick={handleAction}>
        Aktion auslösen
      </button>
    </div>
  );
};