Integrációs dokumentáció

Hogyan kösd be a push.onemin.hu Web Push szolgáltatást a mobilappodba / weboldaladba és a backendedbe. Tesztpanel · Kezdőlap.

Hogyan működik (3 résztvevő)

1. Mobilapp / weboldal — megnyitja a feliratkozó URL-t a böngészőben.
2. push.onemin.hu — feliratkozó oldal, eltárolja a böngésző subscription-jét DB-be.
3. A te backended — meghívja a /api/send-et az adott usernek, amikor push kell.

mobil/web ─► /subscribe?appId=&userId=  (a böngésző feliratkozik)
                       │
                       ▼
                push.onemin.hu ◄── /api/send (a backended hívja)
                       │
                       ▼
              push provider (Google/Mozilla/Apple)
                       │
                       ▼
                user böngészője megkapja

5 perces beüzemelés

1. App regisztrálás (admin)

Minden külön mobilappnak vagy weboldalnak külön appId-t és saját api kulcsot adsz. Ez egyszeri lépés.

curl -X POST https://push.onemin.hu/api/apps \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GLOBAL_API_KEY" \
  -d '{
    "appId": "catch",
    "name": "Catch",
    "apiKey": "catch-secret-api-key"
  }'

2. A mobilapp megnyitja a linket

Az appodban vagy a weboldaladon egy link / gomb erre vezet:

https://push.onemin.hu/subscribe?appId=catch&userId=123

A userId a te belső azonosítód a felhasználóra. Lehet szám, UUID, bármi.

3. A user feliratkozik

A user megnyomja a „Feliratkozom" gombot → engedélyezi az értesítéseket → kész. A subscription elmentődik a DB-be.

4. A backended push-t küld

curl -X POST https://push.onemin.hu/api/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: catch-secret-api-key" \
  -d '{
    "appId": "catch",
    "userId": "123",
    "title": "Új foglalás",
    "body": "Valaki most foglalt nálad.",
    "url": "https://app.example.com/bookings/123"
  }'

A user böngészőjében megjelenik az értesítés. Ha rákattint, megnyílik az url.

Mobil / web integráció

A mobilapp csak megnyitja a subscribe URL-t a rendszerböngészőben. Nincs SDK, nincs natív kód a push-hoz.

// build.gradle: implementation "androidx.browser:browser:1.8.0"
val url = "https://push.onemin.hu/subscribe?appId=catch&userId=$userId"
val intent = androidx.browser.customtabs.CustomTabsIntent.Builder().build()
intent.launchUrl(context, android.net.Uri.parse(url))

import SafariServices

let url = URL(string: "https://push.onemin.hu/subscribe?appId=catch&userId=\(userId)")!
let vc = SFSafariViewController(url: url)
present(vc, animated: true)

import { Linking } from 'react-native';

Linking.openURL(
  `https://push.onemin.hu/subscribe?appId=catch&userId=${userId}`
);

// pubspec.yaml: url_launcher: ^6.2.0
import 'package:url_launcher/url_launcher.dart';

await launchUrl(
  Uri.parse('https://push.onemin.hu/subscribe?appId=catch&userId=$userId'),
  mode: LaunchMode.externalApplication,
);

<a href="https://push.onemin.hu/subscribe?appId=catch&userId=123">
  Értesítések bekapcsolása
</a>

Backend integráció

Csak HTTPS POST. Bármelyik szerveroldali nyelvből egysoros.

curl -X POST https://push.onemin.hu/api/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: catch-secret-api-key" \
  -d '{
    "appId": "catch",
    "userId": "123",
    "title": "Új foglalás",
    "body": "Valaki most foglalt nálad."
  }'

async function sendPush(userId, title, body, url) {
  const res = await fetch('https://push.onemin.hu/api/send', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.PUSH_API_KEY,
    },
    body: JSON.stringify({ appId: 'catch', userId, title, body, url }),
  });
  if (!res.ok) throw new Error('push hiba: ' + await res.text());
  return res.json();
}

function sendPush($userId, $title, $body, $url = null) {
  $payload = ['appId' => 'catch', 'userId' => $userId, 'title' => $title, 'body' => $body];
  if ($url) $payload['url'] = $url;

  $ch = curl_init('https://push.onemin.hu/api/send');
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
      'Content-Type: application/json',
      'X-API-Key: ' . getenv('PUSH_API_KEY'),
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
  ]);
  $out = curl_exec($ch);
  curl_close($ch);
  return json_decode($out, true);
}

import os, requests

def send_push(user_id, title, body, url=None):
    payload = {"appId": "catch", "userId": user_id, "title": title, "body": body}
    if url: payload["url"] = url
    r = requests.post(
        "https://push.onemin.hu/api/send",
        headers={"X-API-Key": os.environ["PUSH_API_KEY"]},
        json=payload, timeout=10,
    )
    r.raise_for_status()
    return r.json()

Endpoint referencia

Auth header: X-API-Key. Egy app api kulcsa nem tud más app nevében küldeni — az appId-t a szerver ellenőrzi.

Notification payload

iOS különlegesség

Apple csak iOS / iPadOS 16.4-től engedi a Web Push-t, és csak akkor, ha a user kirakta az oldalt a kezdőképernyőre Safariból. A user lépései:

1. Megnyitja Safariban (nem Chrome-ban iPhone-on!).
2. Megosztás ikon.
3. „Hozzáadás a főképernyőhöz".
4. Indítás az új ikonról.
5. Engedélyezi az értesítéseket.

Hibakeresés

• 401 Unauthorized a /api/send-nél: rossz X-API-Key vagy nem ahhoz az appId-hez tartozik.
• 404 / 410 a push providertől: a subscription lejárt — a szerver automatikusan enabled = false-ra állítja.
• iOS-en nem jön az értesítés: a user nem a kezdőképernyőről nyitotta meg, vagy nem 16.4+ az iOS.
• Permission denied: a user blokkolta — böngésző oldali beállításokban kell visszaengednie.
• Minden 0 sikeres a /api/send válaszban: a user még nem iratkozott fel ezen az appId+userId párral. Próbáld a tesztpanelen.

A notification_logs tábla minden küldési próbálkozást rögzít status_code + error mezőkkel — ott pontosan láthatod, mi történt.