Ajouter des métadonnées personnalisées à des clips, des listes de lecture ou des programmes (récupérables via les API Omny et via RSS)
Nous vous guiderons tout au long de la création et de la modification de champs personnalisés pour vos clips, listes de lecture ou programmes, en les définissant comme obligatoires ou facultatifs, et nous vous expliquerons comment l’API se comporte lors de la gestion des champs personnalisés.
Définition des champs personnalisés
Aller dans les paramètres de l'organisation, du réseau ou du programme, en fonction du champ d'application pour lequel vous créez des champs personnalisés. La structure suit la hiérarchie d’héritage des paramètres d’Omny, comme expliqué ici.
Dans le menu Champs personnalisés, vous pouvez voir vos champs personnalisés existants et cliquer sur Créer un champ pour en créer un nouveau au niveau du clip, de la liste de lecture ou du programme.
Donner au champ un nom d’affichage, qui sera ajouté à l’interface utilisateur de la page de détails du clip, du programme ou de la liste de lecture, ainsi qu’un nom d’API. C’est ainsi que ce champ sera étiqueté dans la gestion et (éventuellement) dans l’API consommateur ou le flux RSS.
REMARQUE : veuillez noter que si un champ personnalisé est visible dans l’API consommateur ou le flux RSS, vous devez traitez le nom et le contenu du champ comme publics.
Choisir le type de réponse au contenu que ce champ acceptera, Texte ou Liste déroulante.
Les options déroulantes peuvent être répertoriées dans la case ci-dessous, chaque option sur une nouvelle ligne.
Choisir si ce champ est obligatoire pour qu’un clip, une liste de lecture ou un programme soit enregistré.
REMARQUE : si nécessaire, la valeur du champ personnalisé devra être ajoutée à n’importe quel clip, liste de lecture ou programme (en fonction de la portée de votre champ personnalisé) au sein de l’organisation, du réseau ou du programme avant d’être publié (c’est-à-dire rendu non répertorié ou public) et enregistré. Les clips et listes de lecture privés ne nécessitent pas la saisie des champs obligatoires avant l’enregistrement. Une valeur doit être saisie avant d’enregistrer un nouveau programme, car ces options de visibilité ne s’appliquent pas au niveau du programme.
Si vous le souhaitez, ajoutez une description pour ce champ personnalisé afin d’aider les utilisateurs de votre compte à l’utiliser.
Enregistrer les modifications.
Utilisation des champs personnalisés
Lorsque les champs personnalisés sont actifs, un nouvel ajout sera ajouté à la page de détails du clip, de la liste de lecture ou du programme.
Les champs obligatoires sont marqués de la mention « (requis) » et si aucune sélection ou donnée n’est saisie dans un champ obligatoire, cela empêchera un utilisateur de publier ou d’enregistrer.
Récupération des champs personnalisés
Les clips avec des champs personnalisés seront inclus dans le service de webhooks Omny ou dans les API Omny, à la fois dans l’API de gestion et dans l’API client (facultatif).
Vous pouvez également ajouter vos champs personnalisés à vos flux RSS. Si vous choisissez cette option, les champs personnalisés s’afficheront dans le format suivant :
<omny:clipCustomField key="my-test-clip-field" value="test"/>
<omny:playlistCustomField key="my-test-playlist-custom-field" value="test"/>
<omny:programCustomField key="my-test-program-custom-field" value="test"/>API de gestion
Les champs personnalisés peuvent également être définis et mis à jour sur les clips via l’API de gestion, mais les règles de validation diffèrent légèrement. Ceux-ci sont documentés ci-dessous. Notez que les valeurs déroulantes ne sont pas validées lorsqu’elles sont définies via l’API.
Pour définir des champs personnalisés sur un clip, il faut les inclure dans la propriété CustomFieldData comme suit :
POST /v0/clips/{clipId}
{
"Id" : "Guid",
...
"CustomFieldData" :
{
"my-custom-field" : "value1",
"another-custom-field" : "value2"
}
}Si des champs personnalisés sont omis d’une mise à jour ou définis sur null, leur valeur existante est conservée. De même, définir « CustomFieldData » comme null préservera toutes les données des champs personnalisés.
Pour effacer un champ personnalisé, il faut passer une chaîne vide dans la requête API pour ce champ, comme suit :
POST /v0/clips/{clipId}
{
"Id" : "Guid",
...
"CustomFieldData" :
{
"my-custom-field" : ""
}
}Faire de même pour les champs personnalisés au niveau de la liste de lecture et du programme.
Créer une validation de point de terminaison
Lors de la création d’un nouveau clip, d’une nouvelle liste de lecture ou d’un nouveau programme, tous les champs marqués comme obligatoires sont requis si la création publie également le clip ou la liste de lecture. La validation d'un programme est effectuée lors de sa sauvegarde.
Mettre à jour la validation du point de terminaison
Lors de la mise à jour d’un clip ou d’une playlist déjà publié, il n'est pas nécessaire d’ajouter de valeurs pour les nouveaux champs personnalisés requis pour la publication. Les champs obligatoires qui ont des valeurs existantes ne peuvent pas être effacés, ils peuvent seulement être modifiés.
Validation du point de terminaison de publication
Tous les champs personnalisés obligatoires sont validés lors de la publication d’un clip ou d’une playlist via le point de terminaison de publication.
Pour toute question, veuillez contacter l’assistance Omny.