Référence des objets d'application (BÊTA)

L’utilisation de cette fonctionnalité nécessite une autorisation de HubSpot. Si vous souhaitez demander l’accès aux objets d’application ou si vous souhaitez en savoir plus sur les fonctionnalités, veuillez soumettre ce formulaire.

Découvrez ci-dessous des informations de référence pour les fonctionnalités d’application de la plateforme de développement avec des objets d’application, y compris des définitions de fichier de configuration, des détails de domaines, etc.

Structure du projet

Tous les composants du projet doivent se trouver dans le répertoire indiqué src dans le fichier de configuration hsproject.json.
Toutes les fonctionnalités et tous les composants de l’application doivent se trouver dans le répertoire app/.
Les associations d’objets d’application sont définies dans le répertoire app-object-associations/.
Les abonnements Webhook sont définis dans le répertoire webhooks/.
Les actions de workflow personnalisées sont définies dans le répertoire workflow-actions/.
Toutes les caractéristiques des cartes doivent se trouver dans le répertoire cards/.
Toutes les instances de composants et de fonctionnalités sont déclarées à l’aide de fichiers *-hsmeta.json. Vous devez faire précéder le nom du fichier d’un élément significatif (par exemple, my-app-hsmeta.json). Ces fichiers doivent se trouver à la racine de leur dossier respectif (par exemple, app/my-app-hsmeta.json, cards/my-card-hsmeta.json).

L’exemple de structure de répertoire ci-dessous décrit toutes les fonctionnalités disponibles.

my-folder/
├── hsproject.json
├──src
│   ├── app/
│   │   └── app-hsmeta.json/
│   │   └── app-objects/
│   │     └── my-app-object-hsmeta.json
│   │   └── app-object-associations/
│   │     └── my-app-object-association-hsmeta.json
│   │   └── webhooks/
│   │     └── webhooks-hsmeta.json
│   │   └── cards/
│   │     └── my-app-card-hsmeta.json
│   │     └── MyCard.jsx
└──

Afficher un exemple sur GitHub

Objets de l’application

Pour créer un objet d’application, incluez un répertoire de composants app-objects dans le projet, ainsi qu’un fichier de configuration.

...
├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── app-objects/
│   │     └── my-app-object-hsmeta.json
└──

Voici les options de configuration disponibles pour *-object-hsmeta.json.

{
  "uid": "car-app-object",
  "type": "app-object",
  "config": {
    "name": "CAR",
    "appPrefix": "Vroom",
    "description": "An automobile in our warehouse.",
    "singularForm": "Car",
    "pluralForm": "Cars",
    "primaryDisplayLabelPropertyName": "model",
    "secondaryDisplayLabelPropertyNames": ["make"],
    "settings": {
      "hasRecordPage": true,
      "allowsUserCreatedRecords": true,
      "hasEngagements": true
    },
    "properties": [
      {
        "type": "string",
        "fieldType": "text",
        "name": "model",
        "label": "Model",
        "description": "The model of the car"
      },
      {
        "type": "enumeration",
        "fieldType": "select",
        "name": "make",
        "label": "Make",
        "description": "The manufacturer of the car.",
        "options": [
          {
            "label": "Ford",
            "value": "ford",
            "displayOrder": 0
          },
          {
            "label": "Toyota",
            "value": "toyota",
            "displayOrder": 1
          },
          {
            "label": "Chevrolet",
            "value": "chevrolet",
            "displayOrder": 2
          }
        ]
      }
    ]
  }
}

Afficher un exemple sur GitHub

Les champs marqués par * sont requis.

Champ	Type	Description
`uid`*	Chaîne	un identifiant unique pour l’objet application. Doit être globalement unique au sein du projet.
`type`*	Chaîne	le type de composant. Doit correspondre au nom du dossier parent (`app-object`).
`name`*	Chaîne	le nom de l’objet de votre application. Utilisez le nom approuvé que vous avez reçu dans la confirmation de votre application approuvée. Doit être en majuscule snake case (`MY_OBJECT_NAME`).
`appPrefix`	Chaîne	une chaîne qui précède le nom singulier ou pluriel de l’objet dans l’interface utilisateur de HubSpot pour aider à le différencier des autres objets. Dans cet exemple, les éléments `appPrefix` de `Vroom` et `singularForm` de `Car` entraînent l’affichage de « Voiture Vroom » dans l’interface utilisateur.
`description`*	Chaîne	la description de l’objet, qui s’affichera dans HubSpot.
`singularForm`*	Chaîne	la forme singulière du nom d’objet.
`pluralForm`*	Chaîne	la forme plurielle du nom d’objet.
`properties`*	Tableau	une liste des propriétés CRM définies pour l’objet. Les propriétés sont définies en utilisant les mêmes champs que l’API des propriétés. Les propriétés résultantes auront automatiquement `a<appId>_` ajouté à elles (par exemple, `a12345_make`) lors de la création. Vous ne devez pas inclure le préfixe dans le fichier de configuration.
`primaryDisplayLabelPropertyName`*	Chaîne	le nom de la propriété qui doit être utilisée comme propriété d’affichage principale. La valeur doit correspondre au nom fourni dans la liste `properties` (autrement dit, elle ne doit pas inclure le préfixe généré `a<appId>_`).
`secondaryDisplayLabelPropertyNames`*	Tableau	la liste des propriétés qui doivent être utilisées comme propriétés d’affichage secondaires. La valeur doit correspondre au nom fourni dans la liste `properties` (autrement dit, elle ne doit pas inclure le préfixe généré `a<appId>_`).
`settings`*	Objet	un objet contenant des paramètres d’objet.
`hasRecordPage`*	Booléen	indique si des pages de fiches d’informations existent pour les instances de cet objet d’application. Si défini sur `false`, la page d’index existera toujours, mais elle ne comprendra pas de liens vers des pages de fiches d’informations individuelles.
`allowsUserCreatedRecords`*	Booléen	si les utilisateurs finaux pourront créer des fiches d’informations à l’aide de l’objet. Lorsque la valeur est définie sur `false`, les utilisateurs ne pourront pas créer de fiches d’informations dans HubSpot
`hasEngagements`*	Booléen	si les fiches d’informations d’objet d’application prennent en charge des activités/engagements. Lorsque définie sur `false`, les pages de fiches d’informations d’objet d’application n’incluront aucune fonctionnalité d’engagement, comme l’onglet d’activité ou les filtres de chronologie liés à l’activité.

Le nom entièrement qualifié (FQN) pour votre objet d’application sera a<appId>_<objectName>. Par exemple : si votre appId est 16858319 et que le nom d’objet de l’application est CARS, alors le FQN serait a16858319_CARS. Vous utiliserez le FQN lors de la définition des valeurs de domaine pour les vos objets d’application.

Schéma de l’application

Pour créer un objet d’application, incluez un fichier de configuration app-hsmeta.json dans le répertoire app.

...
├──src
│   ├── app/
│   │   └── app-hsmeta.json/
└──

Voici les options de configuration disponibles pour app-hsmeta.json.

Résumé des modifications

Prenez note des modifications suivantes pour les fichiers de configuration des cartes d’application :

Ajout des champs de premier niveau uid, type et config.
Champ extensions supprimé.
Champ distribution ajouté.

{
  "uid": "app_object_poc_app",
  "type": "app",
  "config": {
    "description": "An example to demonstrate how to build an app with an app object on developer projects.",
    "name": "my first app object app",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": ["crm.objects.contacts.read", "crm.objects.contacts.write"],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.hubapi.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

Afficher un exemple sur GitHub

Schéma d’application *champs -hsmeta.json

Les champs marqués par * sont requis

Champ	Type	Description
`uid`*	Chaîne	un identifiant unique interne pour l’application. Doit être globalement unique au sein du projet. Peut être n’importe quelle chaîne jusqu’à 64 caractères. Les caractères peuvent être en majuscules ou en minuscules, et peuvent inclure des chiffres, des tirets bas (`_`), des tirets (`-`) et des points (`.`).
`type`*	Chaîne	le type de composant. Doit correspondre au nom du dossier parent (`app`).
`description`*	Chaîne	une description de ce que l’application fait pour l’utilisateur qui l’installe. Peut être n’importe quelle chaîne jusqu’à 8 192 caractères.
`name`*	Chaîne	le nom de l’application, qui s’affichera dans HubSpot. Peut être n’importe quelle chaîne jusqu’à 200 caractères. Ne doit pas commencer ou se terminer par un espace.
`distribution`*	Chaîne	la méthode de distribution de l’application. Doit être défini sur `marketplace` pour que l’application soit éligible au listing du marketplace des applications.
`auth`*	Objet	un objet contenant les détails de la méthode d’authentification de l’application. Voir le tableau des authentifications pour plus de détails.
`permittedUrls`	Objet	un tableau contenant les URL que l’application est autorisée à appeler. Les URL doivent utiliser le schéma HTTPS et contenir une autorité, suivie d’un préfixe de chemin facultatif si nécessaire.
`supportEmail`	Chaîne	une adresse e-mail valide que les utilisateurs peuvent contacter pour obtenir de l’aide.
`documentationUrl`	Chaîne	l’URL externe vers laquelle les utilisateurs peuvent accéder pour obtenir de la documentation utile. Doit utiliser HTTPS.
`supportUrl`	Chaîne	l’URL externe vers laquelle les utilisateurs peuvent accéder pour obtenir une assistance supplémentaire. Doit utiliser HTTPS.
`supportPhone`	Chaîne	le numéro de téléphone que les utilisateurs peuvent contacter pour obtenir de l’aide. Doit commencer par un signe plus (`+`).

champs d’authentification

Les champs marqués par * sont requis.

Champ	Type	Description
`type`*	Chaîne	le type d’authentification. Doit être défini sur `oauth` pour que l’application utilise l’authentification OAuth.
`redirectUrls`*	Tableau	une liste des URL vers lesquelles le processus OAuth est autorisé à rediriger. Chaque application doit avoir au moins une URL de redirection d’authentification et doit utiliser HTTPS. La seule exception est `http://localhost`, qui est autorisée pour les tests.
`requiredScopes`*	Tableau	une liste des domaines requis de votre application. Chaque application doit inclure au moins un domaine et l’utilisateur qui a procédé à l’installation doit accorder ces domaines pour installer l’application avec succès. Découvrez-en davantage sur les domaines ci-dessous.
`optionalScopes`	Tableau	une liste des domaines facultatifs de votre application. Ces domaines peuvent être exclus de l’autorisation lors de l’installation si le compte ou l’utilisateur qui installe l’application ne dispose pas des autorisations appropriées. Dans ce cas, le domaine ne sera pas inclus dans le jeton d’actualisation ou le jeton d’accès qui en résulte. Découvrez-en davantage sur les domaines ci-dessous.
`conditionallyRequiredScopes`	Tableau	une liste des domaines requis uniquement lorsqu’ils sont inclus dans le paramètre de requête `scope` de l’URL d’installation. Découvrez-en davantage sur les domaines ci-dessous.

Domaines

Dans le champ auth d’un fichier de configuration d’application, vous pouvez indiquer trois types de domaines : les domaines requis, les domaines conditionnellement requis et les domaines facultatifs. À ce stade de la version bêta, vous devez inclure uniquement les domaines d’objet de votre application en tant que conditionallyRequiredScopes. Cela vous permettra de réserver vos nouvelles fonctionnalités à des clients spécifiques en incluant les domaines d’objet d’application dans l’URL d’installation. Les domaines d’objet d’application utilisent le format suivant : crm.app.schemas.<appObjectFullyQualifiedName>.read Par exemple, pour un objet application avec le FQN a16858319_cars, le domaine d’application read serait : crm.app.schemas.a16858319_cars.read. Au minimum, votre application doit inclure le domaine ci-dessus read pour permettre aux clients d’accéder à l’objet. Il est recommandé d’inclure tous les domaines d’application dans votre application, comme indiqué ci-dessous.

"auth": {
      "type" : "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write",
        "crm.app.objects.a12345_MY_APP_OBJECT.view",
        "crm.app.objects.a12345_MY_APP_OBJECT.create",
        "crm.app.objects.a12345_MY_APP_OBJECT.edit",
        "crm.app.schemas.a12345_MY_APP_OBJECT.read",
        "crm.app.objects.a12345_MY_APP_OBJECT.merge",
        "crm.app.objects.a12345_MY_APP_OBJECT.delete",
        "crm.app.schemas.a12345_MY_APP_OBJECT.properties.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },

Pour obtenir une liste complète des domaines disponibles, consultez la référence des domaines.

Définition du composant Webhook

Pour définir un ensemble d’abonnements au webhook pour votre application, incluez un répertoire webhooks dans le projet ainsi qu’un fichier de configuration *-hsmeta.json.

├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── webhooks/
│   │     └── webhooks-hsmeta.json
└──

Vous trouverez ci-dessous les options de configuration disponibles pour le fichier *-hsmeta.json.

{
  "uid": "webhooks",
  "type": "webhooks",
  "config": {
    "settings": {
      "targetUrl": "https://example.com/webhook",
      "maxConcurrentRequests": 10
    },
    "subscriptions": {
      "crmObjects": [
        {
          "subscriptionType": "object.creation",
          "objectType": "contact",
          "active": true
        },
        {
          "subscriptionType": "object.propertyChange",
          "objectType": "car_app_object",
          "propertyName": "carProperty",
          "active": true
        }
      ],
      "legacyCrmObjects": [
        {
          "subscriptionType": "contact.propertyChange",
          "propertyName": "lastname",
          "active": true
        },
        {
          "subscriptionType": "contact.deletion",
          "active": true
        }
      ],
      "hubEvents": [
        {
          "subscriptionType": "contact.privacyDeletion",
          "active": true
        }
      ]
    }
  }
}

Webhook *champs -hsmeta.json

Les champs marqués par * sont requis.

Champ	Type	Description
`uid`*	Chaîne	un identifiant unique interne pour le composant du webhook.
`type`*	Chaîne	le type de composant, qui devrait être `webhooks` dans ce cas.
`settings`*	Objet	un objet qui spécifie deux champs : `targetUrl`, qui est l’URL publique que HubSpot peut appeler l’endroit où les charges utiles de l’événement seront livrées, et `maxConcurrentRequests`, qui est le seuil supérieur des demandes HTTP que HubSpot effectuera dans une période donnée.
`subscriptions`*	Objet	un objet qui spécifie les types d’abonnements auxquels votre application s’abonnera.
`crmObjects`	Tableau	un tableau contenant des définitions d’abonnement aux événements. Il s’agit du tableau standard à inclure, qui doit être utilisé pour tous les événements dans le nouveau format (`object.*`). Les types d’abonnement de webhook classiques doivent plutôt être inclus dans les tableaux `legacyCrmObjects` et `hubEvents`, en fonction de l’événement.
`legacyCrmObjects`	Tableau	un tableau contenant les types d’abonnements classiques, tels que `contact.creation` et `deal.deletion`.
`hubEvents`	Tableau	un tableau contenant les types `contact.privacyDeletion` d’abonnements classiques et `conversation.*`

Pour chaque objet subscription, les champs suivants peuvent être indiqués, en fonction du type de définition d’abonnement auquel vous êtes abonné (c’est-à-dire crmObjects, legacyCrmObjects ou hubEvents) ou selon que vous êtes abonné à une modification de propriété spécifique (par exemple, contact.propertyChange).

Champ	Type	Description
`subscriptionType`	Chaîne	le type d’événement auquel l’abonné est abonné.
`objectType`	Chaîne	pour les abonnements indiqués dans le tableau `crmObjects`, cela indique l’objet CRM auquel votre application est abonnée. Pour vous abonner aux modifications apportées à un objet d’application, incluez le nom de votre objet d’application pour ce champ (par exemple, `car_app_object`).
`propertyName`	Chaîne	pour les abonnements de modification de propriété, cela indique la propriété qui déclenchera l’événement webhook.
`active`	Booléen	si des événements webhook seront déclenchés pour cet abonnement.

Schéma de carte d’application

Pour créer une carte d’application qui apparaît sur une page de fiches d’informations d’un objet d’application, incluez un répertoire de composant cards dans le projet, ainsi qu’un fichier de configuration.

├──src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── cards/
│   │     └── my-app-card-hsmeta.json
│   │     └── MyCard.jsx
└──

Vérifiez que vous avez exécuté hs project upload après avoir créé votre composant d’objet d’application et les fichiers de configuration associés.
Dans votre fichier my-app-card-hsmeta.json, ajoutez l’UID de votre objet d’application au tableau objectTypes (par exemple, "app_object_uid" dans cet exemple). Chacun des champs disponibles dans le fichier .json est détaillé dans le tableau ci-dessous.

Résumé des modifications

Prenez note des modifications suivantes pour les fichiers de configuration des cartes d’application :

Ajout des champs de premier niveau uid, type et config.
Le champ module a été renommé entrypoint.
Le champ title a été renommé name.
Le champ objectTypes a été simplifié pour accepter un tableau de chaînes.

{
  "uid": "my-app-card",
  "type": "card",
  "config": {
    "name": "My app card",
    "description": "An example description of the card, which lives on contact records.",
    "previewImage": {
      "file": "./preview.png",
      "altText": "A short description of the preview image"
    },
    "entrypoint": "/app/cards/MyCard.jsx",
    "location": "crm.record.tab",
    "objectTypes": ["contacts", "app_object_uid"]
  }
}

Après avoir enregistré les modifications apportées à votre fichier example-card-hsmeta.json, exécutez hs project upload.

Les cartes sont ajoutées automatiquement à la vue par défaut pour les objets d’application. Si la carte ne s’affiche pas automatiquement, découvrez comment ajouter des cartes aux fiches d’informations CRM.

Afficher un exemple sur GitHub

App card *champs -hsmeta.json

Les champs marqués par * sont requis.

Champ	Type	Description
`uid`*	Chaîne	l’identifiant unique de la carte. Il peut s’agir de n’importe quelle chaîne, mais doit identifier la carte de manière significative. HubSpot identifiera la carte par cet ID afin que vous puissiez modifier le titre de la carte sans supprimer les données historiques ou d’état, telles que la position sur la fiche d’informations CRM.
`type`	Chaîne	le type de composant, qui devrait être `card` dans ce cas.
`config`	Objet	un objet contenant des détails de configuration.
`name`*	Chaîne	le titre de la carte, tel qu’il apparaît dans l’interface utilisateur de HubSpot.
`description`	Chaîne	une description de la carte.
`previewImage`	Objet	un objet contenant les champs `file` et `altText`. Le champ `file` est le chemin relatif vers l’image d’aperçu. Les extensions de fichier valides sont png, jpeg, jpg ou gif. La taille maximale du fichier est de 5.0 Mo. Le champ `altText` est une courte description de l’image.
`entrypoint`*	Chaîne	le chemin du fichier du code React front-end de la carte.
`location`*	`crm.record.tab` \| `crm.record.sidebar` \| `helpdesk.sidebar`	Emplacement de la carte dans l’interface utilisateur de HubSpot En savoir plus sur l’emplacement de l’extension.
`objectTypes`*	Tableau	les types de fiches d’informations CRM sur lesquels la carte apparaîtra.

Associations d’objets d’application

Pour activer les associations entre votre objet application et d’autres objets CRM, incluez un répertoire de composants app-object-associations dans le projet, ainsi qu’un fichier de configuration.

├── src
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── app-object-associations/
│   │     └── my-app-object-association-hsmeta.json
└──

Voici les options de configuration d’objet d’application disponibles (*-association-hsmeta.json).

{
  "uid": "car_to_contact_association",
  "type": "app-object-association",
  "config": {
    "firstObjectType": "car-app-object",
    "secondObjectType": "CONTACT"
  }
}

Association *champs -association-hsmeta.json

Les champs marqués par * sont requis.

Champ	Type	Description
`uid`*	Chaîne	un identifiant unique interne pour l’application. Doit être globalement unique au sein du projet.
`type`*	Chaîne	le type de composant. Doit correspondre au nom du dossier parent (`app-object-association`).
`config`*	Objet	un objet contenant la configuration de l’association d’objets.
`firstObjectType`*	Chaîne	le premier objet de l’association. Il peut s’agir d’un objet d’application ou d’un objet CRM HubSpot. Les objets d’application sont désignés par leur `uid` indiqué dans leur fichier source. Les objets standards sont désignés par leur `fullyQualifiedName`. L’association résultante sera bidirectionnelle, de sorte que l’ordre de ces valeurs de champ est arbitraire.
`secondObjectType`*	Chaîne	le deuxième objet de l’association. Voir `firstObjectType` pour plus de détails.

Créer des applications

Ajouter des fonctionnalités

Publier dans la Marketplace HubSpot

Référence des objets d'application (BÊTA)

Structure du projet

Afficher un exemple sur GitHub

Objets de l’application

Afficher un exemple sur GitHub

Schéma de l’application

Afficher un exemple sur GitHub

Schéma d’application *champs -hsmeta.json

champs d’authentification

Domaines

Définition du composant Webhook

Webhook *champs -hsmeta.json

Schéma de carte d’application

Afficher un exemple sur GitHub

App card *champs -hsmeta.json

Associations d’objets d’application

Association *champs -association-hsmeta.json

​Structure du projet

Afficher un exemple sur GitHub

​Objets de l’application

Afficher un exemple sur GitHub

​Schéma de l’application

Afficher un exemple sur GitHub

​Schéma d’application *champs -hsmeta.json

​champs d’authentification

​Domaines

​Définition du composant Webhook

​Webhook *champs -hsmeta.json

​Schéma de carte d’application

Afficher un exemple sur GitHub

​App card *champs -hsmeta.json

​Associations d’objets d’application

​Association *champs -association-hsmeta.json

Structure du projet

Objets de l’application

Schéma de l’application

Schéma d’application *champs -hsmeta.json

champs d’authentification

Domaines

Définition du composant Webhook

Webhook *champs -hsmeta.json

Schéma de carte d’application

App card *champs -hsmeta.json

Associations d’objets d’application

Association *champs -association-hsmeta.json