AlertSync Webhook API: מדריך למפתחי base44

מסמך זה מסביר כיצד לשלב את אפליקציית base44 עם שירות AlertSync לצורך שליחת התראות Push למשתמשים באמצעות OneSignal.

⚙️ זרימת העבודה החדשה

הארכיטקטורה החדשה מפרידה באופן ברור בין האחריויות:

1. **רישום מכשיר (באחריות AlertSync):**
* אפליקציית base44 מפנה את המשתמש לדף ייעודי ב-AlertSync לצורך רישום לקבלת התראות.
* **כתובת ההפניה:** https://your-alertsync-domain.com/register?userId=USER_ID_FROM_YOUR_SYSTEM&returnUrl=URL_TO_RETURN_TO
* בדף זה, AlertSync משתמש ב-SDK של OneSignal וגם ב-SDK של Firebase כדי לבקש הרשאה מהמשתמש ולקבל מזהי מכשיר.
* לאחר אישור, AlertSync שומר את המזהים (playerId ו-fcmToken) בבסיס הנתונים שלו, משויכים ל-userId שקיבל.

2. **תזמון התראה (באחריות base44):**
* כאשר מערכת base44 רוצה לשלוח התראה למשתמש, היא שולחת בקשת POST ל-Webhook של AlertSync.
* הבקשה מכילה את ה-userId של המשתמש (לא את ה-playerId) ויכולה לציין אם להשתמש ב-onesignal או firebase.

3. **שליחה על ידי AlertSync:**
* שירות AlertSync מקבל את הבקשה.
* בזמן השליחה, המערכת מחפשת בבסיס הנתונים שלה איזה מזהה מכשיר (playerId או fcmToken) משויך ל-userId שהתקבל, בהתאם לספק שנבחר.
* AlertSync שולח את ההתראה למשתמש דרך ה-API של הספק המתאים.

---

🚀 שלב 1: הפניית משתמש לרישום

כדי לרשום משתמש לקבלת התראות, הפנה אותו מהמערכת שלך לכתובת הבאה. החלף את USER_ID_FROM_YOUR_SYSTEM במזהה הייחודי של המשתמש במערכת base44, והוסף returnUrl (מקודד) כדי להחזיר את המשתמש לאפליקציה שלך לאחר הצלחה.

https://studio--alertsync-g4usl.us-central1.hosted.app/register?userId=USER_ID_FROM_YOUR_SYSTEM&returnUrl=URL_ENCODED_RETURN_URL

**דוגמה:** עבור משתמש עם המזהה client-54321, שצריך לחזור לדף https://my.base44.com/settings:
https://studio--alertsync-g4usl.us-central1.hosted.app/register?userId=client-54321&returnUrl=https%3A%2F%2Fmy.base44.com%2Fsettings

בדף זה, המשתמש יתבקש לאשר קבלת התראות. AlertSync יטפל בכל תהליך הרישום מול OneSignal ו-Firebase, שמירת הנתונים, והפניית המשתמש בחזרה בסיום.

---

🧐 שלב 1.5 (אופציונלי): בדיקת סטטוס רישום

לפני תזמון התראה, ניתן לבדוק האם למשתמש מסוים יש לפחות מכשיר אחד רשום במערכת.

### Endpoint

- **URL**: https://studio--alertsync-g4usl.us-central1.hosted.app/api/devices/status/[userId]
- **Method**: GET
- **URL Params**:
- userId (string, required): The unique user ID from your base44 system.

### Authentication

הנקודה מוגנת באמצעות מפתח API. יש לכלול את המפתח בהידר x-api-key.

- **Header Name**: x-api-key
- **Value**: AIzaSyC0n-Rfy4FtI4_S_D6inv1qsayoE8U8gM4

### תגובה (Response)

גוף התגובה יכיל אובייקט JSON עם המידע הבא:

Field	Type	Description
isRegistered	boolean	true אם למשתמש יש לפחות מכשיר אחד רשום, אחרת false.
deviceCount	number	מספר המכשירים הרשומים עבור המשתמש.

#### דוגמת תגובה (משתמש רשום)

{
  "isRegistered": true,
  "deviceCount": 2
}

#### דוגמת פקודת curl

# Replace user_101 with the actual User ID you want to check
curl -X GET \
  -H "x-api-key: AIzaSyC0n-Rfy4FtI4_S_D6inv1qsayoE8U8gM4" \
  https://studio--alertsync-g4usl.us-central1.hosted.app/api/devices/status/user_101

---

📬 שלב 2: תזמון התראה (Webhook)

לאחר שהמשתמש נרשם, תוכל לשלוח בקשה ל-Webhook של AlertSync כדי לתזמן עבורו התראה, **תוך שימוש ב-userId שלו**.

### Endpoint

- **URL**: https://studio--alertsync-g4usl.us-central1.hosted.app/api/webhook
- **Method**: POST

### Authentication

הנקודה מוגנת באמצעות מפתח API. יש לכלול את המפתח בהידר x-api-key.

- **Header Name**: x-api-key
- **Value**: AIzaSyC0n-Rfy4FtI4_S_D6inv1qsayoE8U8gM4 (ניתן לשנות ב-.env של פרויקט AlertSync).

### Headers

- Content-Type: application/json
- x-api-key: AIzaSyC0n-Rfy4FtI4_S_D6inv1qsayoE8U8gM4

### Request Body Schema

Field	Type	Required	Description
userId	string	Yes	The unique user ID from your base44 system.
alertType	string	Yes	The type of the alert (e.g., "High Temperature", "Security Breach").
sendAt	string	Yes	An ISO 8601 formatted date-time string indicating when the alert should be sent.
provider	string	No	The notification provider. Can be 'onesignal' or 'firebase'. Defaults to 'onesignal' if not provided.
alertDetails	string	No	Optional detailed information about the alert.
appName	string	No	Optional name of the application sending the alert. This will be used as the push notification title. Defaults to "Base44 Alert" if not provided.
webUrl	string	No	Optional URL to open when the notification is clicked. Defaults to https://aspaklaria.base44.app/ if not provided.
timestamp	string	No	An ISO 8601 formatted date-time string for when the event occurred. If not provided, the server will use the current time.

#### דוגמת בקשה (Request Body)

{
  "userId": "user_101",
  "alertType": "Security Breach",
  "alertDetails": "Unauthorized access attempt detected from IP 192.168.1.100.",
  "sendAt": "2024-08-15T10:35:00Z",
  "timestamp": "2024-08-15T10:30:00Z",
  "appName": "Base44 Security",
  "provider": "onesignal",
  "webUrl": "https://aspaklaria.base44.app/dashboard/security"
}

### דוגמת פקודת curl

# Replace user_101 with the actual User ID from your system
# This example will send the notification via the 'onesignal' provider with a default URL
curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: AIzaSyC0n-Rfy4FtI4_S_D6inv1qsayoE8U8gM4" \
  -d '{
        "userId": "user_101",
        "alertType": "High Temperature",
        "alertDetails": "CPU temperature has exceeded 90°C.",
        "sendAt": "'$(date -u -v+1M +'%Y-%m-%dT%H:%M:%SZ')'",
        "appName": "Base44",
        "provider": "onesignal"
      }' \
  https://studio--alertsync-g4usl.us-central1.hosted.app/api/webhook

---

### תגובות (Responses)

- **201 Created:** הבקשה התקבלה בהצלחה וההתראה תוזמנה.
- **400 Bad Request:** גוף הבקשה אינו תקין או שחסרים שדות חובה.
- **401 Unauthorized:** המפתח x-api-key חסר או שגוי.
- **500 Internal Server Error:** שגיאה פנימית בשרת.