Apps

Eigene App bauen

Die App ist deine Webseite: im Look von Packlets, mit packlets.js, Anmeldung per Session-Token und Mitteilungen unter der Glocke.

Als Markdown öffnen

Eine App ist eine Webseite, die du selbst baust. Packlets zeigt sie als Kachel im Tab Apps und öffnet sie unter dem Kopf der App, so breit wie der Bildschirm. Du hast alle Freiheit von HTML, und mit packlets.css sieht deine Seite trotzdem aus wie Packlets.

Kanal oder App

KanalApp
So geht esDein Tool schickt Nachrichten, Packlets zeigt sie untereinander.Die ganze App ist deine Webseite.
Du brauchstnur HTTP-Aufrufeeinen Server, der die Seite über https:// ausliefert
Gut fürMeldungen: ein Server fällt aus, ein Deploy schlägt fehl, eine Bestellung kommt reinArbeit mit Listen und Daten: Rechnungen freigeben, Bestellungen ansehen, Tickets beantworten
Aussehenimmer wie Packletsmit packlets.css wie Packlets, sonst frei
Bedienung kommt an alsWebhook-Ereignisnormale Anfrage deiner Seite an deinen Server

Fang mit einem Kanal an, wenn dein Tool sich vor allem melden soll. Auch dort gehen Knöpfe, Schalter, Diagramme und Tabellen, als Elemente in Nachrichten. Eine App lohnt sich, wenn du immer wieder etwas nachsehen oder abarbeiten willst.

Ideen, was eine App sein kann:

  • Rechnungen freigeben: Jede offene Rechnung als Karte. Wisch nach rechts gibt sie frei, nach links lehnt sie ab.
  • Server und Deploys: Status deiner Dienste, letzte Deploys, Knöpfe für Neustart und Rollback.
  • Freigaben: Pull Requests oder Spesen ansehen und mit einem Tipp freigeben.
  • Support-Postfach: Neue Anfragen lesen und kurz antworten.
  • Bestellungen: Die Bestellungen deines kleinen Shops von heute, offen und versendet.

Wer Shopify kennt: Es ist dasselbe Prinzip wie bei eingebetteten Shopify-Apps mit App Bridge und Session-Token.

Du brauchst: einen Server mit https-Adresse, der deine Seite ausliefert.

1. Die Seite bauen

Eine normale HTML-Seite. Zwei Dateien von Packlets machen sie zur App: packlets.css für das Aussehen und packlets.js für die Verbindung zur App.

html
<!doctype html>
<html lang="de">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="https://packlets.app/embed/packlets.css">
    <script src="https://packlets.app/embed/packlets.js"></script>
  </head>
  <body>
    <main class="packlets">
      <div class="packlets-row packlets-spread">
        <div>
          <p class="packlets-label" id="firma">Rechnung</p>
          <p class="packlets-big" id="betrag">–</p>
          <p class="packlets-sub" id="info"></p>
        </div>
        <span class="packlets-chip" id="offen"></span>
      </div>
      <div class="packlets-row">
        <button class="packlets-button is-secondary packlets-grow" onclick="entscheide('ablehnen')">Ablehnen</button>
        <button class="packlets-button packlets-grow" onclick="entscheide('freigeben')">Freigeben</button>
      </div>
    </main>
    <script>
      let rechnung;
      async function naechste() {
        const res = await packlets.fetch("/api/rechnungen/naechste");
        rechnung = await res.json();
        document.getElementById("firma").textContent = rechnung.firma;
        document.getElementById("betrag").textContent = rechnung.betrag;
        document.getElementById("info").textContent = `Fällig am ${rechnung.faellig} · ${rechnung.nummer}`;
        document.getElementById("offen").textContent = `${rechnung.offen} offen`;
      }
      async function entscheide(aktion) {
        const res = await packlets.fetch(`/api/rechnungen/${rechnung.id}/${aktion}`, { method: "POST" });
        if (!res.ok) return packlets.toast("Das hat nicht geklappt");
        packlets.haptic("success");
        naechste();
      }
      naechste();
    </script>
  </body>
</html>

Die Klassen wie packlets-row und packlets-button kommen aus packlets.css. Alle stehen in der Referenz.

2. Die Seite zur App machen

Tippe in Packlets im Tab Apps oben links auf das Plus, wähle Eine eigene App und gib ihr einen Namen. Dann schickt dein Tool einmal die Adresse deiner Seite:

Shell
curl -X PUT https://api.packlets.app/v1/ui \
  -H "Authorization: Bearer $PACKLETS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": "https://dein-server.de/rechnungen"}'

Antwort: {"ok": true, "page": "https://dein-server.de/rechnungen"}. Packlets zeigt Verbunden!, und die Kachel steht im Tab Apps.

  • Nur https://. Im Body steht nur page.
  • Beim ersten Öffnen zeigt Packlets die Adresse deiner Seite und fragt nach, bevor es sie lädt. Wechselst du später auf eine andere Adresse (anderer Host oder Port), fragt Packlets erneut.
  • Eine andere Adresse setzt du mit einem neuen PUT.
  • Einmal reicht. Was die Seite zeigt, bestimmt danach dein Server.

3. Mit der App sprechen: packlets.js

Über das Objekt packlets nutzt deine Seite, was nur die App kann:

AufrufWas passiert
packlets.toast("Gespeichert")Kurze Meldung in der App.
packlets.haptic("success")Vibration.
packlets.open("https://…")Öffnet eine Adresse im Browser.
await packlets.fetch(url, init)Wie fetch(), aber mit Anmeldung. Siehe nächster Schritt.
packlets.ready()Seite ist fertig, Packlets blendet den Platzhalter aus (mit data-ready="manual").
packlets.storage.set("ort", "Berlin")Speichert Text auf dem Gerät, getrennt nach Konto.

Packlets hält geöffnete Seiten im Speicher. Kommt jemand zurück, ist deine Seite sofort da, ohne neu zu laden, und bekommt das Ereignis packlets:activated. Die Farben von Packlets stehen als CSS-Variablen bereit (--packlets-bg, --packlets-text, --packlets-cta …).

Im normalen Browser gibt es die App nicht, und die Aufrufe schlagen fehl. Frag deshalb vorher packlets.inPacklets ab, wenn deine Seite auch dort laufen soll:

html
<script>
  if (!packlets.inPacklets) document.body.textContent = "Öffne diese Seite in Packlets.";
</script>

Alle Aufrufe stehen in der Referenz.

4. Wissen, wer die Seite öffnet

Deine Seite ist öffentlich erreichbar. Zeigt sie private Daten, muss dein Server wissen, dass die Anfrage wirklich aus deiner App in Packlets kommt. Ein eigenes Login brauchst du dafür nicht: Packlets weiß schon, wer angemeldet ist, und bestätigt es deinem Server mit einem Session-Token.

In PackletsDeine Seiteruft packlets.fetch() auf, das holt ein frisches Token
packlets.token()Token
DazwischenPackletsstellt ein JWT aus, 60 Sekunden gültig, signiert mit deinem Schlüssel
Bearer-Tokendeine Daten
Bei dirDein Serverprüft das Token und weiß, wer die Seite öffnet
  1. Deine Seite ruft packlets.fetch() auf. Das holt bei Packlets ein frisches Token und schickt es als Authorization: Bearer … an deinen Server.
  2. Dein Server prüft das Token. Stimmt es, weiß er, wer die Seite öffnet.

Das Token ist ein JWT, 60 Sekunden gültig und signiert mit einem Geheimnis, das nur du und Packlets kennen: dem SHA-256-Hash deines Schlüssels. Geprüft wird auf deinem Server:

import hashlib, os
import jwt  # pip install pyjwt

SECRET = hashlib.sha256(os.environ["PACKLETS_KEY"].encode()).hexdigest()
PACKLET_ID = os.environ["PACKLETS_APP_ID"]

def packlets_user(request):
    token = request.headers.get("Authorization", "").removeprefix("Bearer ")
    claims = jwt.decode(token, SECRET, algorithms=["HS256"], audience=PACKLET_ID)
    return {"id": claims["sub"], "email": claims.get("email"), "name": claims.get("name")}

Schlägt die Prüfung fehl, werfen beide Funktionen einen Fehler. Antworte dann mit 401.

  • PACKLETS_APP_ID ist die ID deines Packlets. Du bekommst sie in der Seite mit (await packlets.info()).packlet_id, und sie steht in jedem Webhook-Ereignis als packlet_id.
  • Kein Cookie, keine Sitzung. packlets.fetch() holt für jede Anfrage ein frisches Token.
  • Ohne JWT-Bibliothek kann dein Server das Token auch von Packlets prüfen lassen.

Achtung: Der Schlüssel gehört auf deinen Server, nie in die Seite. Was im HTML oder JavaScript steht, kann jeder lesen.

5. iframes und fremde Inhalte

Deine Seite selbst ist kein iframe: Packlets zeigt sie in einem eigenen Browser in der App. Zwei Dinge solltest du trotzdem regeln.

Fremde Inhalte in deiner Seite. Bettest du ein iframe von einer anderen Adresse ein (Video, Karte, Widget), kann es packlets nicht benutzen. Packlets gibt der Seite beim Laden einen geheimen Brücken-Schlüssel, den nur deine Seite sieht, und ignoriert jeden Aufruf ohne ihn. Was das iframe sonst tut, entscheidest du:

html
<iframe src="https://www.youtube-nocookie.com/embed/…"
        sandbox="allow-scripts allow-same-origin"
        referrerpolicy="no-referrer"></iframe>
  • sandbox immer setzen und nur freigeben, was das iframe braucht. Ohne allow-top-navigation kann es deine Seite nicht wegschicken, ohne allow-popups keine Fenster öffnen.
  • Fremde Skripte (Werbung, Tracking) direkt in deiner Seite laufen mit allen Rechten deiner Seite, auch mit packlets.fetch(). Bind nur Skripte ein, denen du vertraust.
  • Inhalte von Nutzern nie als HTML einsetzen (innerHTML), sondern als Text (textContent).

Deine Seite in fremden Seiten. Deine Adresse ist öffentlich. Eine andere Webseite könnte sie in ein iframe laden und Nutzer zu Klicks verleiten. Ein Token bekommt sie dort nicht, weil es Packlets dort nicht gibt. Verbiete das Einbetten trotzdem mit einem Header deines Servers:

HTTP
Content-Security-Policy: frame-ancestors 'none'
X-Frame-Options: DENY

Packlets stört das nicht, denn die App bettet deine Seite nicht in ein iframe ein.

6. Mitteilungen schicken

Deine App kann sich melden, auch wenn sie gerade niemand offen hat: Die Rechnungs-App sagt Bescheid, wenn neue Rechnungen warten, das Server-Dashboard, wenn ein Dienst ausfällt. Dafür schickt dein Server eine Nachricht, mit demselben Aufruf wie ein Kanal: POST /v1/push mit dem Schlüssel der App.

curl https://api.packlets.app/v1/push \
  -H "Authorization: Bearer $PACKLETS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "3 neue Rechnungen", "text": "Zusammen **1.284,50 €**, die erste ist am Freitag fällig."}'

Die Antwort ist {"message_id": "…"}, wie bei jeder Nachricht. Dann passiert in Packlets dreierlei:

Mitteilungen

Rechnungen

3 neue Rechnungen9:41

Zusammen 1.284,50 €, die erste ist am Freitag fällig.

Rechnung abgelehntGestern

Druckerei Weber, RE-2207: Betrag stimmt nicht mit dem Angebot überein.

Die Glocke oben rechts in der App: alle Mitteilungen, neueste zuerst
  1. Push aufs Handy. Im Push steht der Name der App, dazu title und der Anfang von text. Tippst du ihn an, öffnet sich die App. Der Push kommt auch, wenn die App gerade offen ist.
  2. Zähler auf der Kachel. Im Tab Apps zeigt die Kachel, wie viele Mitteilungen ungelesen sind. Öffnest du die App, gelten alle als gelesen.
  3. Verlauf unter der Glocke. Oben rechts in jeder App sitzt eine Glocke. Sie zeigt alle Mitteilungen der App, die neueste oben, zehn auf einmal und weitere beim Scrollen. Der Verlauf liegt auch auf dem Handy und ist darum sofort da, ohne Netz mit dem letzten Stand. Neben der Glocke lädt ein Knopf deine Seite neu.

Was unter der Glocke steht

FeldUnter der Glocke
titleFett als Überschrift. Ohne title steht dort „Mitteilung“.
textMit Formatierung. Lange Texte sind gekürzt und klappen beim Antippen auf.
urlAntippen öffnet den Link. Darunter steht die Adresse. Zeig hier am besten auf die passende Stelle deiner Seite.
priorityWie bei Kanälen: Ton, stumm oder Push trotz Ruhezeit. Siehe Push, Ton und Ruhezeit.
image, buttons, elementsWerden angenommen, aber nicht gezeigt. Lass sie weg: Bedienen gehört auf deine Seite.

Tipps

  • Kurz und konkret. Eine Mitteilung sagt, dass etwas wartet. Die Arbeit selbst passiert auf deiner Seite.
  • Seite aktualisieren. Kommt jemand über den Push in die App, war die Seite vielleicht noch im Speicher. Lade deine Daten neu, sobald das Ereignis packlets:activated kommt:
html
<script>
  addEventListener("packlets:activated", () => naechste());
</script>
  • Nicht für jede Kleinigkeit. Es gelten dieselben Grenzen wie für Kanäle: 60 Aufrufe pro Minute und App. Fass mehrere Ereignisse lieber zu einer Mitteilung zusammen („3 neue Rechnungen“).
  • Push, Ton und Ruhezeit stellt jeder selbst in den Einstellungen der App ein. Tippe dafür in der App oben auf Avatar oder Namen.
  • Ohne Code: Auch die Adressen für Slack, Discord und ntfy funktionieren mit dem Schlüssel einer App. So landen zum Beispiel Meldungen deines CI-Systems unter der Glocke.

Damit es sich wie eine App anfühlt

  • Weißer Hintergrund, kein eigener Rahmen und kein Schatten außen herum.
  • Kein eigener Kopf. Name und Avatar zeigt Packlets schon. Was wichtig ist, gehört nach oben.
  • Tippflächen mindestens 44 Pixel hoch, Text mindestens 12 Pixel.
  • Kein Hover, keine Pop-ups, kein alert(). Für Meldungen gibt es packlets.toast().
  • Links auf deiner eigenen Adresse bleiben in der App. Links zu anderen Adressen öffnen sich im Browser.
  • Testen kannst du im Browser in Handy-Breite, zum Beispiel mit 375 Pixeln in den Entwicklerwerkzeugen.

Ausprobieren

Die beiden Seiten oben sind echte Apps:

  • Wetter zeigt, wie frei du gestalten kannst. Jedes neue Konto hat sie in Packlets unter Apps.
  • Konto zeigt das Session-Token: Die Seite holt bei jeder Anfrage ein frisches Token, ihr Server prüft es und zeigt deinen Namen. Im Browser zeigt dieselbe Seite nur einen Hinweis, denn dort gibt es kein Token.

Checkliste

  • Adresse der Seite mit PUT /v1/ui und {"page": "https://…"} geschickt.
  • <meta name="viewport" content="width=device-width, initial-scale=1"> gesetzt.
  • packlets.css und packlets.js eingebunden.
  • Anfragen an deinen Server laufen über packlets.fetch().
  • Dein Server prüft bei jeder Anfrage Signatur, Ablauf und aud des Tokens.
  • Der Schlüssel steht nur auf dem Server.
  • Fremde iframes mit sandbox, deine Seite mit frame-ancestors 'none' ausgeliefert.
  • Mitteilungen schickt dein Server mit POST /v1/push, kurz und mit url auf die passende Stelle deiner Seite.

Wie es weitergeht

  • Alle Aufrufe von packlets.js, das Token und packlets.css: Referenz.
  • Feld, Antwort und Fehler von PUT /v1/ui: PUT /v1/ui.
  • Alle Felder einer Mitteilung: POST /v1/push.