Passer au contenu principal
L’envoi des données de consommation est la première chose à faire pour libérer le potentiel d’Hyperline lorsque vous avez un modèle basé sur la consommation, mais il y a quelques conseils pour tirer le meilleur parti de notre système. Tout d’abord, nous ne sommes pas une API d’analytique, nous envoyer des vues de pages, des connexions d’utilisateurs ou d’autres événements non critiques n’a pas vraiment de sens car vous ne les utiliserez probablement pas pour votre tarification et packaging de toute façon. Cela étant dit, vous ne devriez pas vous retenir d’envoyer des données que vous n’utilisez pas encore. Hyperline est conçu pour vous permettre d’itérer sur votre tarification et packaging et vous permettra de faire des expérimentations et des simulations à partir des données que nous avons ingérées. La meilleure façon de penser aux événements à nous envoyer est de vous demander si vous utiliserez les données soit
  • Pour tarifer votre produit (ex : prix par utilisateur ou par appel API)
  • Pour limiter la consommation (ex : gratuit jusqu’à 5 Go de stockage)
  • Pour orchestrer des workflows liés à la tarification (ex : lorsqu’un client atteint X, afficher un paywall).
En cas de doute, envoyez-les simplement, une fois dans le système, vous pourrez jouer avec et pourrez découvrir de nouvelles opportunités.

​
Bases de l’ingestion

Les payloads d’événements suivent toujours la même structure et peuvent être envoyés à l’endpoint POST /events. L’objet record peut contenir n’importe quelles propriétés supplémentaires de type string, number, boolean et tableau de ces types, mais les tableaux d’objets seront rejetés. Les événements sont traités instantanément, vous pouvez aller sur votre page d’événements et la rafraîchir pour les voir. L’API d’ingestion d’événements est limitée à 1 000 requêtes toutes les 10 secondes. Lors de l’envoi d’événements en lot, chaque requête peut contenir jusqu’à 5 000 événements. Voir limitation de débit pour plus de détails. Voici un exemple de payload
Event
{
  "customer_id": "cus_fh4585Jjrekkk",
  "timestamp": "2022-01-05 21:56:52",
  "event_type": "new_transaction",
  "record": {
    "id": 485,
    "amount": 2500
  }
}

​
Sécurité et confidentialité

Même si nous effectuons quelques vérifications de sécurité de base, nous ne pouvons pas filtrer automatiquement toutes les données personnelles ou confidentielles de nos systèmes. La plupart du temps, vous n’avez pas besoin d’informations personnelles dans Hyperline, nous vous recommandons donc de les supprimer ou de les masquer (par exemple, John devient J***).
  • Noms de personnes
  • Adresses e-mail personnelles
  • Numéros de téléphone
  • Informations de paiement comme les numéros de carte ou IBAN
  • Adresses physiques
  • Tout ce qui pourrait aider à identifier l’identité ou la localisation de quelqu’un
Dans nos systèmes, nous sommes responsables de la sécurité de vos données, mais vous êtes en charge du contenu lui-même, donc soyez prudent, la sécurité de vos clients est une question importante.

​
Événements ou entités ?

Hyperline est conçu pour s’appuyer entièrement sur les événements pour l’ingestion des données. Nous pouvons ensuite appliquer une variété d’opérateurs pour configurer comment vous souhaitez agréger les données (count, sum), et des filtres (equals, vérification « is null », comparateurs supérieur/inférieur à, etc.).
Dans le premier cas, Hyperline traitera vos événements comme des entités ou modèles, ce qui signifie qu’un événement représentera un élément dans notre base de données, indépendamment de son horodatage. Par exemple, disons que vous voulez que votre client paie 5€ par utilisateur, vous nous enverrez l’événement suivant lorsqu’un nouvel utilisateur est inscrit.
Event
{
  "customer_id": "<customer_id>", // Hyperline ID or external ID of the existing customer
  "timestamp": "2023-11-12T00:00:00.000Z", // used to aggregate depending on the billing period
  "event_type": "users", // use the name you want
  "record": {
    "id": 258,
    "work_email": "l***.c***@yourcompany.com",
    "created_at": "2023-11-12T00:00:00.000Z",
    "deleted_at": null // we'll use this field later
  }
}
Vous créerez ensuite un produit dynamique qui compte vos utilisateurs et lui appliquerez une tarification par volume en définissant un intervalle et les paliers de tarification associés.
Nous vous proposons un aperçu de l’évolution de cette tarification pour la rendre plus visible quant à son évolution avec l’augmentation des éléments.

​
Mettre à jour et supprimer des événements

Vous vous demandez peut-être ce qui se passe si j’envoie un événement qui ne devrait pas être facturé ? Ou si je dois modifier une entité ? L’API d’Hyperline est un système en append-only, ce qui signifie qu’à l’exception de notre interface, nous ne permettons pas les opérations de mise à jour ou de suppression. Mais ne vous inquiétez pas, nous avons tout prévu.

​
Mettre à jour un événement

Chaque événement est identifié par une clé unique composée de 2 paramètres :
  • event_type
  • record.id
Lorsqu’Hyperline détecte un nouvel événement avec exactement les 2 mêmes clés, il considérera que ce nouvel événement remplace le précédent et le remplacera donc dans la base de données. En d’autres termes, mettre à jour un événement, c’est comme en créer un — renvoyez l’événement avec les mêmes event_type et record.id, et l’événement correspondant sera remplacé. Pour déterminer quel événement est le plus récent, nous utilisons la valeur timestamp.
Seuls les champs record (payload) et timestamp sont mis à jour lors du renvoi d’un événement. Les champs customer_id et event_type sont immuables — ils restent tels que définis par l’événement original et sont ignorés lors de la mise à jour.Si vous avez besoin de changer le client associé à un événement, supprimez l’événement original et créez-en un nouveau.
En reprenant nos utilisateurs, voici un exemple où nous ajoutons une propriété « status » 
{
  "customer_id": "<customer_id>",
  "timestamp": "ACTIVE_DATE",
  "event_type": "users",
  "record": {
    "id": 258,
    "status": "premium",
    "work_email": "l***.c***@yourcompany.com",
    "created_at": "2022-01-01 10:00:00",
    "deleted_at": null
  }
}
L’événement dans la base de données aura maintenant un statut premium et la version précédente n’existera plus. Si vous devez conserver les deux versions, vous devrez fournir un record.id différent.

​
Supprimer un événement

Si vous avez envoyé un événement par erreur, vous pouvez le supprimer dans l’onglet Events de l’application. Mais ce n’est pas la façon de gérer les suppressions standards, par exemple lorsqu’un utilisateur est supprimé d’un compte. Il existe plusieurs façons de gérer cela, la première est d’utiliser la clé deleted_at que nous avons ajoutée plus tôt et de la définir sur quelque chose de différent de null. Ensuite, mettez à jour le produit usage que nous avons créé plus tôt pour filtrer les enregistrements où deleted_at n’est pas nul comme ceci.
Une autre option consiste à utiliser un état ou un flag dans le modèle, par exemple un champ booléen active dans l’entité utilisateur que vous pouvez désactiver. Le principe reste le même, définissez simplement une propriété sur la bonne valeur et filtrez les éléments que vous ne voulez pas.

​
Récupérer des événements via l’API

Vous pouvez récupérer les événements facturables de manière programmatique en utilisant l’endpoint GET /v1/events. Cela vous permet de :
  • Interroger les événements par type d’événement
  • Filtrer par client, IDs d’enregistrement ou plage d’horodatage
  • Trier les résultats par ordre ascendant ou descendant
  • Paginer à travers de grands ensembles de résultats
Ceci est utile pour construire des analyses personnalisées, auditer les données de consommation ou intégrer les données d’événements dans vos propres systèmes.
Example request
curl -H "Authorization: Bearer <API key>" \
  "https://ingest.hyperline.co/v1/events?event_type=api_call&customer_id=cus_xyz789&timestamp_gte=2024-01-01T00:00:00Z"

​
Limitations

Afin de traiter des nombres massifs d’événements, Hyperline a dû adopter une structure rigide pour les événements. Bien qu’assez permissive, il y a 2 limitations principales :
  • Les propriétés d’enregistrement ne peuvent pas être imbriquées (un seul niveau de propriétés est autorisé)
  • Les enregistrements ne peuvent pas avoir plus de 25 propriétés