Notifications

Description

Le composant Notification permet d'envoyer des notifications signées à la plateforme Yeria, qui les distribue ensuite à des utilisateurs précis. Les notifications sont signées avec Ed25519 (comme les vues) puis transmises au backend Yeria (POST {baseUrl}/api/v1/user/notifications). Chaque notification cible un utilisateur unique et contient un message composé d'un titre, d'un corps et, facultativement, de liens de navigation interne.

Caractéristiques principales :

• Ciblage nominatif d'un utilisateur (userId requis)
• Notifications signées avec Ed25519
• Modèle push : le SDK émet vers la plateforme Yeria
• Liens de navigation interne facultatifs
• La plateforme assure la distribution aux utilisateurs

⚠ Abonnement requis (contrôle de consentement fail-closed)

La plateforme Yeria ne distribue une notification que si l'utilisateur destinataire s'est explicitement abonné au service émetteur. Il n'existe aucune primitive de diffusion groupée, ni aucun moyen pour un service de créer un abonnement au nom d'un utilisateur : les abonnements sont toujours déclenchés par l'utilisateur depuis l'application mobile ou web Yeria.

Lorsque votre service signe et transmet une notification en POST :

Les notifications rejetées ne sont pas conservées : votre service ne peut donc pas sonder l'état d'abonnement d'un utilisateur en envoyant des notifications et en inspectant les réponses, au-delà du code d'erreur retourné de manière synchrone.

Parcours d'activation recommandé

Puisque votre service ne peut pas abonner un utilisateur automatiquement, présentez un appel à l'action « Activer les notifications » dans vos vues Yeria dès la première interaction de l'utilisateur avec le service. Cet appel à l'action doit utiliser le lien profond Yeria canonique (yeria://dl/n/{serviceId}, ou https://yeria.app/dl/n/{serviceId}), qui invite l'utilisateur à donner son consentement.

Traitez proprement les codes d'erreur SUBSCRIPTION_* : un 403 renvoyé par l'endpoint de notifications est un résultat attendu pour tout utilisateur qui n'a pas donné son accord, et non une défaillance d'infrastructure. Prévoyez une limitation des relances afin que votre service ne sollicite pas l'endpoint à chaque rejet.

Détail des champs

Structure de la notification sécurisée

Une fois signée, la notification respecte la structure suivante :

Méthodes

Exemple de code JavaScript

Notification simple

1import { YeriaApp, Notification } from '@numerum-tech/yeriasdk';
2
3const yeriaApp = new YeriaApp({
4    appId: 'my-app',
5    baseUrl: 'https://yeria.app'
6});
7
8const notification = new Notification('user-123', 'Welcome!', 'Thank you for joining Yeria')
9    .setLink('/welcome');
10
11const signedNotification = yeriaApp.signNotification(notification);
12// Send manually or use sendNotification()

Notification avec lien interne

1const notification = new Notification(
2    'user-456',
3    'New Message',
4    'You have a new message from John',
5    '/messages/123'  // Optional link parameter
6);
7
8await yeriaApp.sendNotification(notification);

Notification sans lien

1const notification = new Notification(
2    'user-789',
3    'Reminder',
4    'Don\'t forget to complete your profile'
5);
6
7await yeriaApp.sendNotification(notification);

Envoi manuel de la notification

1const notification = new Notification('user-123', 'Alert', 'System maintenance scheduled');
2
3const signedNotification = yeriaApp.signNotification(notification);
4
5// Send manually using your HTTP client
6const response = await fetch('https://yeria.app/api/v1/user/notifications', {
7    method: 'POST',
8    headers: { 'Content-Type': 'application/json' },
9    body: JSON.stringify(signedNotification)
10});

Exemple de code Python

Notification simple

1from yeriasdk import YeriaApp, YeriaAppConfig, Notification
2
3config = YeriaAppConfig(
4    app_id='my-app',
5    base_url='https://yeria.app'
6)
7json_app = YeriaApp(config)
8
9notification = Notification('user-123', 'Welcome!', 'Thank you for joining Yeria')
10notification.set_link('/welcome')
11
12signed_notification = json_app.sign_notification(notification)
13# Send manually or use send_notification()

Notification avec lien interne

1notification = Notification(
2    'user-456',
3    'New Message',
4    'You have a new message from John',
5    link='/messages/123'  # Optional link parameter
6)
7
8json_app.send_notification(notification)

Notification sans lien

1notification = Notification(
2    'user-789',
3    'Reminder',
4    'Don\'t forget to complete your profile'
5)
6
7json_app.send_notification(notification)

Envoi manuel de la notification

1import requests
2
3notification = Notification(
4    'user-123',
5    'Alert',
6    'System maintenance scheduled'
7)
8
9signed_notification = json_app.sign_notification(notification)
10
11# Send manually using requests
12payload = {
13    'appId': signed_notification.app_id,
14    'signature': signed_notification.signature,
15    'timestamp': signed_notification.timestamp,
16    'notification': {
17        'userId': signed_notification.notification.user_id,
18        'message': {
19            'title': signed_notification.notification.message.title,
20            'body': signed_notification.notification.message.body,
21            'link': signed_notification.notification.message.link,
22        }
23    }
24}
25
26response = requests.post(
27    'https://yeria.app/api/v1/user/notifications',
28    json=payload
29)

Exemple JSON complet

1{
2  "appId": "my-app",
3  "signature": "MEUCIQD...",
4  "timestamp": 1706443200000,
5  "notification": {
6    "userId": "user-123",
7    "message": {
8      "title": "Welcome!",
9      "body": "Thank you for joining Yeria",
10      "link": "/welcome"
11    }
12  }
13}

Configuration

YeriaAppConfig

Ajoutez les réglages liés aux notifications dans YeriaAppConfig :

1interface YeriaAppConfig {
2    appId: string;
3    baseUrl?: string;             // Yeria platform base URL (e.g. https://yeria.app)
4    notificationTimeout?: number; // HTTP request timeout in ms (default: 5000)
5    // ... other config options
6}

1@dataclass
2class YeriaAppConfig:
3    app_id: str
4    base_url: Optional[str] = None  # Yeria platform base URL (e.g. https://yeria.app)
5    notification_timeout: int = 5   # HTTP request timeout in seconds
6    # ... other config options

Gestion des erreurs

• MissingRequiredParameterError : levée si userId, title ou body est absent
• ConfigurationError : levée si baseUrl n'est pas renseignée lors de l'appel à sendNotification()
• ExternalError : levée si la requête HTTP échoue lors de l'envoi de la notification

Détails de la signature

Les notifications reposent sur le même mécanisme de signature Ed25519 que les vues :

1. La charge utile de la notification est sérialisée en JSON
2. La charge utile est signée : JSON.stringify({ notification: notificationJson, timestamp, appId })
3. La signature est encodée en base64
4. La notification signée contient appId, signature, timestamp ainsi que la charge utile

Intégration à la plateforme

La plateforme Yeria reçoit les notifications signées par requête HTTP POST :

• Endpoint : {baseUrl}/api/v1/user/notifications (baseUrl issu de YeriaAppConfig)
• Méthode : POST
• Content-Type : application/json
• Corps : JSON de la notification signée (voir l'exemple JSON complet ci-dessus)

La plateforme vérifie la signature puis distribue la notification à l'utilisateur destinataire.