Passer au contenu principal

Plate-forme API : Image cible

L'API de gestion des images cible 8th Wall permet aux développeurs de gérer dynamiquement la bibliothèqued’image cible associée à leurs projets WebAR alimentés par 8th Wall. Cette API et la documentation qui l'accompagne sont conçues pour les développeurs familiarisés avec le développement web et les images cible 8th Wall.

Avant de commencer : Avant de commencer à utiliser l’image cible d’API, votre espace de travail doit être sur un plan de facturation *Entreprise. Pour effectuer une mise à niveau, contacter le service des ventes.

Authentification

L'authentification est assurée par des clés secrètes. Les espaces de travail d'un plan Entreprise peuvent demander une clé API. Vous inclurez cette clé secrète dans chaque demande pour vérifier que la demande est autorisée. Étant donné que la clé se trouve dans votre espace de travail, elle aura accès à toutes les images cible dans toutes les applications de cet espace de travail.

Vous pouvez consulter votre clé sur la page de votre compte.

Visualisation des images cible dans les applications, des applications dans l'espace de travail et de la clé API dans l'espace de travail

Important

La clé d’image cible d’API est une clé B2B associée à votre espace de travail. Suivez les meilleures pratiques pour sécuriser votre clé API car l'exposition publique de votre clé API peut entraîner une utilisation involontaire et un accès non autorisé. En particulier, veuillez éviter de :

  • Intégrer la clé image cible d’API dans un code qui s'exécute sur l'appareil d'un utilisateur ou qui est partagé publiquement
  • Stocker la clé clé image cible d’API dans l'arborescence source de votre application

Limites et quotas

  • 25 requêtes par minute, avec une allocation de 500, ce qui signifie que vous pouvez effectuer 500 requêtes en une minute , puis 25 requêtes par minute ensuite, ou attendre 20 minutes et effectuer à nouveau 500 requêtes.
  • 10 000 demandes par jour.

** Note** : Ces limites ne s'appliquent qu'à l'API de gestion d’images cible, qui permet aux développeurs de gérer dynamiquement la bibliothèque d'images associée à un projet 8th Wall. Ces limites ne sont pas applicables aux activations par l'utilisateur final d'une expérience de RA Web.

Pour demander une augmentation des quotas de clé d’image cible d’API pour les projets de votre espace de travail , veuillez envoyer une demande au support.

Points finaux

Créer une image cible

Téléchargez une nouvelle cible dans la liste des images cible d’une application

Requête

curl -X POST "https://api.8thwall.com/v1/apps/$APP_KEY/targets" \N-
-H "X-Api-Key:$SECRET_KEY" \N-
-F "name=my-target-name" \N-
-F "image=@image.png"\N-
-F "geometry.top=0"\N-
-F "geometry.left=0"\N-
-F "geometry.width=480"\N-
-F "geometry.height=640"\N-
-F "metadata={\"customFlag\":true}"
-F "loadAutomatically=true"
ChampTypeValeur par défautDescription
imageDonnées binairesFormat PNG ou JPEG, au moins 480x640, moins de 2048x2048 et moins de 10MB
nomChaîneDoit être unique au sein d'une application, ne peut pas inclure de tildes (~) et ne peut pas dépasser 255 caractères
type [Facultatif]ChaînepLANARpLANAR", "CYLINDER", ou "CONICAL".
métadonnées [Facultatif]ChaînenulDoit être un JSON valide si metadataIsJson est vrai, et ne peut pas dépasser 2048 caractères
metadataIsJson [Optionnel]BooléenvraiVous pouvez définir la valeur faux pour utiliser la propriété de métadonnées en tant que chaîne brute
loadAutomatically [Facultatif]BooléenfauxChaque application est limitée à 5 images cible avec loadAutomatically: vrai
geometry.isRotated [Optionnel]BooléenfauxLa valeur vrai est utilisée si l'image est pré-tournée de l'horizontale à la verticale.
géométrie.hautentierCes propriétés spécifient le recadrage à appliquer à votre image. Elle doit avoir un rapport hauteur/largeur de 3:4 et au moins 480x640.
géométrie.gaucheentier
géométrie.largeurentier
géométrie.hauteurentier
géométrie.topRadiusentierUniquement nécessaire pour type : "CONICAL"
geometry.bottomRadiusentierUniquement nécessaire pour type : "CONICAL"

Géométrie de chargement planaire / cylindrique

Ce diagramme montre comment le recadrage spécifié est appliqué à votre image téléchargée pour générer les images imageUrl et thumbnailImageUrl. Le rapport largeur/hauteur est toujours de 3:4.

Diagramme montrant comment le recadrage, la rotation et la mise à l'échelle sont appliqués aux cibles planaires et cylindriques

Pour un recadrage de paysage, téléchargez l'image avec une rotation de 90 degrés dans le sens des aiguilles d'une montre, définissez geometry.isRotated : true, et spécifiez le recadrage par rapport à l'image ayant subi une rotation.

Diagramme montrant comment le recadrage, la rotation et l'échelle sont appliqués aux cibles d'images planes et cylindriques lorsque isRotated est vrai

Géométrie des charges coniques

Ce diagramme montre comment votre image téléchargée est aplanie et recadrée en fonction des paramètres. L'image téléchargée se présente sous la forme d'un "arc-en-ciel" dans lequel les bords supérieur et inférieur de votre contenu sont alignés sur deux cercles concentriques. Si votre cible est plus étroite en haut qu'en bas, indiquez topRadius comme la valeur négative du rayon extérieur, et bottomRadius comme le rayon intérieur (positif). Pour un recadrage de paysage , définissez geometry.isRotated : true, et l'image aplatie subira une rotation avant l'application du recadrage.

Diagramme montrant comment le recadrage, la rotation et l'échelle sont appliqués aux cibles d'images coniques

Réponse

Il s'agit du format de réponse JSON standard pour les images cible.

{
"name": "...",
"uuid": "...",
"type": "PLANAR",
"loadAutomatically": true,
"status": "AVAILABLE",
"appKey": "...",
"geometry": {
"top": 842,
"left": 392,
"width": 851,
"height": 1135,
"isRotated": true,
"originalWidth": 2000,
"originalHeight": 2000
},
"metadata": null,
"metadataIsJson": true,
"originalImageUrl": "https://cdn.8thwall.com/image-target/...",
"imageUrl": "https://cdn.8thwall.com/image-target/...",
"thumbnailImageUrl": "https://cdn.8thwall.com/image-target/...",
"geometryTextureUrl": "https://cdn.8thwall.com/image-target/...",
"created": 1613508074845,
"updated": 1613683291310
}
PropriétéTypeDescription
nomChaîne
uuidChaîneID unique de cette image cible
typeChaînepLANAIRE", "CYLINDRE", ou "CONIQUE"
loadAutomaticallyBooléen
statutChaîneaVAILABLE" ou "TAKEN_DOWN" (disponible)
appKeyChaîneL'application à laquelle appartient la cible
géométrieObjetVoir ci-dessous
métadonnéesChaîne
metadataIsJsonBooléen
originalImageUrlChaîneURL CDN pour l'image source qui a été chargée
imageUrlChaîneVersion recadrée de geometryTextureUrl
thumbnailImageUrlChaîneversion haute de 350px del'imageUrl à utiliser dans les vignettes
geometryTextureUrlChaînePour les coniques, il s'agit d'une version aplatie de l'image originale, pour les planaires et les cylindriques, c'est la même chose que originalImageUrl
crééentierDate de création en millisecondes après l'époque Unix
mis à jourentierDate de la dernière mise à jour en millisecondes après l'époque unix

Géométrie planaire

PropriétéTypeDescription
sommetentier
gaucheentier
largeurentier
hauteurentier
isRotatedBooléen
largeur originaleentierLargeur de l'image chargée
hauteur originaleentierHauteur de l'image téléchargée

Cylindre ou géométrie conique

Étend les propriétés de la géométrie planaire en précisant que originalWidth et originalHeight font référence aux dimensions de l'image aplatie stockée dans geometryTextureUrl.

PropriétéTypeDescription
topRadiusflotteur
rayon du basflotteur
coninessflotteurToujours 0 pour le type : CYLINDRE, dérivé de topRadius/bottomRadius pour type : CONIQUE
cylindreCirconférenceTopflotteurLa circonférence du cercle complet tracé par le bord supérieur de votre cible
targetCircumferenceTopflotteurLa longueur du bord supérieur de votre cible avant le recadrage
cylinderCircumferenceBottomflotteurDérivé de cylinderCircumferenceTop et topRadius/bottomRadius
longueur du côté du cylindreflotteurDérivé de targetCircumferenceTop et des dimensions de l'image originale
arcAngleflotteurDérivé de cylinderCircumferenceTop et targetCircumferenceTop
mode d'entréeChaînebASIC" ou "ADVANCED". Contrôle ce que les utilisateurs voient dans la console 8th Wall, qu'il s'agisse de curseurs ou de champs de saisie de nombres.

Liste des images cible

Demande d'une liste d'images cible appartenant à une application. Les résultats sont paginés, ce qui signifie que si l'application contient plus de cibles d'images que ce qui peut être renvoyé en une seule réponse, vous devrez faire plusieurs demandes pour énumérer la liste complète des images cible.

Requête

curl "https://api.8thwall.com/v1/apps/$APP_KEY/targets" -H "X-Api-Key:$SECRET_KEY"
ParamètresTypeDescription
par [Facultatif]ChaîneSpécifie la colonne à trier. Les options sont "created", "updated", "name" ou "uuid".
dir [Facultatif]ChaîneContrôle le sens de tri de la liste. Soit "asc", soit "desc".
start [Facultatif]ChaîneSpécifie que la liste commence par les éléments qui ont cette valeur dans la colonne par
après [Facultatif]ChaîneSpécifie que la liste commence immédiatement après les éléments qui ont cette valeur
limite [Facultatif]entierDoit être compris entre 1 et 500
continuation [Facultatif]ChaîneUtilisé pour rechercher la page suivante après la requête initiale.

Liste triée

Cette requête énumère les cibles de l'application en partant de "z" et en allant vers "a".

curl "https://api.8thwall.com/v1/apps/$APP_KEY/targets?by=name&dir=desc" -H "X-Api-Key:$SECRET_KEY"

Tris multiples

Vous pouvez spécifier un paramètre secondaire de "tri par" qui permet de départager les doublons dans votre premier site par la valeur . uuid est utilisé comme critère d'égalité par défaut s'il n'est pas spécifié.

curl "https://api.8thwall.com/v1/apps/$APP_KEY/targets?by=updated&by=uuid" -H "X-Api-Key:$SECRET_KEY"

Spécifiez un point de départ

Vous pouvez spécifier début ou après valeurs qui correspondent aux valeurs par pour spécifier votre position actuelle dans la liste. Si vous voulez que votre liste commence immédiatement après l'élément avec mis à jour : 333 et uuid : 777, vous devez utiliser :

curl "https://api.8thwall.com/v1/apps/$APP_KEY/targets?by=updated&by=uuid&start=333&after=777" -H "X-Api-Key:$SECRET_KEY"

De cette façon, les éléments avec mis à jour : 333 sont toujours inclus dans la page suivante si leur uuid `` vient après 777. Si la valeur mise à jour d'un élément est supérieure à 333, mais que son uuid est inférieur à 777, il sera tout de même inclus dans la page suivante, car la deuxième propriété par n'entre en jeu qu'en cas d'égalité.

Il n'est pas possible de spécifier une valeur après pour le tri principal tout en fournissant une valeur début pour le tri subsidiaire. Par exemple, il ne serait pas valide de spécifier ?by=name&by=uuid&after=my-name-&start=333. Il faudrait plutôt écrire?by=name&by=uuid&after=my-name- parce que le deuxième point de départ n'entre en jeu que lorsque le point de départ principal est inclusif (en utilisant start).

Diagramme montrant comment les paramètres by, start et after spécifient le point de départ de la liste

Réponse

Objet JSON contenant la propriété cible, qui est un tableau d'objets cibles d'images dans leformat standard .

Si continuationToken est présent, vous devrez spécifier ?continuation=[continuationToken] dans une demande de suivi pour obtenir la page suivante des images cible.

{
"continuationToken": "...",
"targets": [{
"name": "...",
"uuid": "...",
"type": "PLANAR",
"loadAutomatically": true,
"status": "AVAILABLE",
"appKey": "...",
"geometry": {
"top": 842,
"left": 392,
"width": 851,
"height": 1135,
"isRotated": true,
"originalWidth": 2000,
"originalHeight": 2000
},
"metadata": null,
"metadataIsJson": true,
"originalImageUrl": "https://cdn.8thwall.com/image-target/...",
"imageUrl": "https://cdn.8thwall.com/image-target/...",
"thumbnailImageUrl": "https://cdn.8thwall.com/image-target/...",
"geometryTextureUrl": "https://cdn.8thwall.com/image-target/...",
"created": 1613508074845,
"updated": 1613683291310
}, {
"name": "...",
"uuid": "...",
"type": "CONICAL",
"loadAutomatically": true,
"status": "AVAILABLE",
"appKey": "...",
"geometry": {
"top": 0,
"left": 0,
"width": 480,
"height": 640,
"originalWidth": 886,
"originalHeight": 2048,
"isRotated": true,
"cylinderCircumferenceTop": 100,
"cylinderCircumferenceBottom": 40,
"targetCircumferenceTop": 50,
"cylinderSideLength": 21.63,
"topRadius": 1600,
"bottomRadius": 640,
"arcAngle": 180,
"coniness": 1.3219280948873624,
"inputMode": "BASIC"
},
"metadata": "{\"my-metadata\": 34534}",
"metadataIsJson": true,
"originalImageUrl": "https://cdn.8thwall.com/...",
"imageUrl": "https://cdn.8thwall.com/...",
"thumbnailImageUrl": "https://cdn.8thwall.com/...",
"geometryTextureUrl": "https://cdn.8thwall.com/...",
"created": 1613508074845,
"updated": 1613683291310
}]
}

Obtenir l’image cible

Requête

curl "https://api.8thwall.com/v1/targets/$TARGET_UUID" -H "X-Api-Key:$SECRET_KEY"

Réponse

Objet JSON du format cible del'image standard

Modifier l’image cible

Les propriétés suivantes peuvent être modifiées :

  • nom
  • loadAutomatically
  • métadonnées
  • metadataIsJson

Les mêmes règles de validation s'appliquent que pour le chargement initial

Pour les cibles cylindriques et coniques, les propriétés suivantes de l'objet geometry peuvent également être modifiées :

  • cylindreCirconférenceTop
  • targetCircumferenceTop
  • mode d'entrée

Les autres propriétés géométriques de la cible seront mises à jour en conséquence.

Requête

curl -X PATCH "https://api.8thwall.com/v1/targets/$TARGET_UUID"\N-
-H "X-Api-Key:$SECRET_KEY"\N-
-H "Content-Type : application/json"\N-
--data '{"name":"new-name", "geometry: {"inputMode": "BASIC"}, "metadata" : "{}"}'

Réponse

Objet JSON du format cible del'image standard

Supprimer l’image cible

Requête

curl -X DELETE "https://api.8thwall.com/v1/targets/$TARGET_UUID" -H "X-Api-Key:$SECRET_KEY"

Réponse

Une suppression réussie renvoie une réponse vide avec le code de statut 204 : Pas de contenu.

Aperçu de l’image cible

Générer une URL que les utilisateurs peuvent utiliser pour prévisualiser le suivi d'une cible.

Requête

curl "https://api.8thwall.com/v1/targets/$TARGET_UUID/test" -H "X-Api-Key:$SECRET_KEY"

Réponse

{
"url": "https://8w.8thwall.app/previewit/?j=...",
"token": "...",
"exp": 1612830293128
}
PropriétéTypeDescription
urlChaîneL'URL qui peut être utilisée pour prévisualiser le suivi de la cible
jetonChaîneCe jeton ne peut actuellement être utilisé que par notre application de prévisualisation.
expentierL'heure en millisecondes à laquelle le jeton expirera. Les jetons expirent une heure après leur émission.

La fonctionnalité de prévisualisation est destinée à être utilisée dans le contexte d'un utilisateur spécifique qui gère ou configure des images cible. Ne publiez pas les URL de prévisualisation sur un site public et ne les partagez pas avec un grand nombre d'utilisateurs.

Meilleures pratiques pour les expériences de prévisualisation personnalisées : L'URL de prévisualisation renvoyée par l'API est l'expérience cible de l'image de prévisualisation générique de 8th Wall. Si vous souhaitez personnaliser davantage l'interface de l'aperçu de votre cible d'image, procédez comme suit :

  1. Créer un projet public 8th Wall
  2. Personnalisez l'interface utilisateur de ce projet en fonction de vos spécifications
  3. Chargez les images cibles que les utilisateurs veulent tester via l'API en utilisant la clé d'application du projet que vous avez créé à l'étape 1
  4. Générez une URL d'image cible testable pour les utilisateurs finaux en utilisant l'URL publique du projet à l'étape 1 et un paramètre URL avec le nom de l’image cible
  5. Dans le projet que vous avez créé à l'étape 1, utilisez le paramètre URL pour définir l'image cible active en utilisant call XR8.XrController.configure({imageTargets: ['theTargetName']}).

Gestion des erreurs

Si l'API rejette votre demande, la réponse sera Content-Type : application/json, et le corps contiendra une propriété message contenant une chaîne d'erreur.

Exemple

{
"message" : "App not found : ..."
}

Codes d'état

StatutRaison
400Cela peut se produire si vous avez spécifié une valeur non valide ou si vous avez fourni un paramètre qui n'existe pas.
403Cela peut se produire si vous ne fournissez pas votre clé secrète correctement.
404L'application ou l'image cible a pu être supprimée, ou la clé de l'application ou l'UUID de la cible est incorrect. Il s'agit également du code de réponse si la clé API fournie ne correspond pas à la ressource à laquelle vous tentez d'accéder.
413L'image chargée a été rejetée car le fichier est trop volumineux.
429Votre clé API a dépassé la limite de débit qui lui est associée.