Referencia de objetos de aplicación (BETA)

Esta función requiere la aprobación de HubSpot para su uso. Si estás interesado en solicitar acceso a los objetos de la aplicación, o si quieres saber más sobre la funcionalidad, envía este formulario de interés.

Abajo encontrarás información de referencia sobre las características de las aplicaciones de la plataforma de desarrollo con objetos de aplicación, incluidas las definiciones de los archivos de configuración, los detalles de los permisos y mucho más.

Estructura del proyecto

Todos los componentes del proyecto deben estar dentro del directorio src especificado en el archivo de configuración hsproject.json.
Todas las funciones y componentes de la aplicación deben estar en el directorio app/.
Las asociaciones de objetos de la aplicación se definen en el directorio app-object-associations/.
Las suscripciones a webhooks se definen en el directorio webhooks/.
Las acciones de workflow personalizadas se definen en el directorio workflow-actions/.
Todas las funciones de la tarjeta deben estar en el directorio cards/.
Todas las instancias de componentes y características se declaran utilizando los archivos *-hsmeta.json. Debes anteponer al nombre del archivo algo significativo (por ejemplo, my-app-hsmeta.json). Estos archivos deben estar en el nivel raíz de sus respectivas carpetas (por ejemplo, app/my-app-hsmeta.json, cards/my-card-hsmeta.json).

El ejemplo de estructura de directorios que aparece abajo describe todas las funciones 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
└──

Ver ejemplo en GitHub

Objetos de aplicación

Para crear un objeto de aplicación, incluye un directorio de componentes app-objects en el proyecto, junto con un archivo de configuración.

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

Abajo se indican las opciones de configuración disponibles para *-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
          }
        ]
      }
    ]
  }
}

Ver ejemplo en GitHub

Los campos marcados con * son obligatorios.

Campo	Tipo	Descripción
`uid`*	Cadena	Un identificador único para el objeto de la aplicación. Debe ser globalmente único dentro del proyecto.
`type`*	Cadena	El tipo de componente. Debe coincidir con el nombre de la carpeta primaria (`app-object`).
`name`*	Cadena	El nombre de tu objeto de aplicación. Utiliza el nombre aprobado que recibiste en la confirmación de tu aplicación aprobada. Debe ser en mayúscula y snake case (`MY_OBJECT_NAME`).
`appPrefix`	Cadena	Una cadena que precede al nombre singular o plural del objeto en la interfaz de HubSpot para ayudar a diferenciarlo de otros objetos. En este ejemplo, `appPrefix` de `Vroom` y `singularForm` de `Car` harían que en la interfaz de usuario apareciera “Vroom Car”.
`description`*	Cadena	la descripción del objeto, que se mostrará en HubSpot.
`singularForm`*	Cadena	La forma singular del nombre del objeto.
`pluralForm`*	Cadena	La forma plural del nombre del objeto.
`properties`*	Matriz	Lista de propiedades del CRM definidas para el objeto. Las propiedades se definen utilizando los mismos campos que la API de propiedades. A las propiedades resultantes se les agregará automáticamente `a<appId>_` (por ejemplo, `a12345_make`) en el momento de la creación. No debes incluir el prefijo en el archivo de configuración.
`primaryDisplayLabelPropertyName`*	Cadena	El nombre de la propiedad que debe utilizarse como propiedad de visualización principal. El valor debe coincidir con el nombre proporcionado en la lista `properties` (es decir, no debe incluir el prefijo generado `a<appId>_`.)
`secondaryDisplayLabelPropertyNames`*	Matriz	La lista de propiedades que deben utilizarse como propiedades de visualización secundarias. El valor debe coincidir con el nombre proporcionado en la lista `properties` (es decir, no debe incluir el prefijo generado `a<appId>_`.)
`settings`*	Objeto	Un objeto que contiene ajustes del objeto.
`hasRecordPage`*	Booleano	Si existen páginas de registro para las instancias de este objeto de aplicación. Si se configura en `false`, la página de índice seguirá existiendo, pero no incluirá enlaces a páginas de registros individuales.
`allowsUserCreatedRecords`*	Booleano	Si los usuarios finales podrán crear registros utilizando el objeto. Si se configura en `false`, los usuarios no podrán crear registros en HubSpot
`hasEngagements`*	Booleano	Si el objeto de la aplicación registra actividades/interacciones de asistencia. Si se establece en `false`, las páginas de registro de objetos de la aplicación no incluirán ninguna funcionalidad de interacción, como la pestaña de actividad o los filtros de cronología relacionados con la actividad.

El nombre completo (FQN) de tu objeto de aplicación será a<appId>_<objectName>. Por ejemplo: si tu appId es 16858319 y el nombre del objeto de la aplicación es CARS, entonces el FQN sería a16858319_CARS. Utilizarás el FQN cuando establezcas valores de alcance para los objetos de tu aplicación.

Esquema de la aplicación

Para crear un objeto de aplicación, incluye un archivo de configuración app-hsmeta.json en el directorio app.

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

Abajo se indican las opciones de configuración disponibles para app-hsmeta.json.

Resumen de cambios

Ten en cuenta los siguientes cambios en los archivos de configuración de las tarjetas de aplicación:

Agregados los campos de nivel superior uid, type y config.
Eliminado el campo extensions.
Agregado el campo distribution.

{
  "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"
    }
  }
}

Ver ejemplo en GitHub

Esquema de la aplicación *-hsmeta.json campos

Los campos marcados con * son obligatorios

Campo	Tipo	Descripción
`uid`*	Cadena	Un identificador único interno para la aplicación. Debe ser globalmente único dentro del proyecto. Puede ser cualquier cadena de hasta 64 caracteres. Los caracteres pueden ser mayúsculas o minúsculas, y pueden incluir números, guiones bajos (`_`), guiones (`-`) y puntos (`.`).
`type`*	Cadena	El tipo de componente. Debe coincidir con el nombre de la carpeta primaria (`app`).
`description`*	Cadena	Descripción de lo que hace la aplicación para el usuario que la instala. Puede ser cualquier cadena de hasta 8192 caracteres.
`name`*	Cadena	El nombre de la aplicación, que se mostrará en HubSpot. Puede ser cualquier cadena de hasta 200 caracteres. No debe empezar ni terminar con un carácter de espacio en blanco.
`distribution`*	Cadena	El método de distribución de la aplicación. Debe estar configurado en `marketplace` para que la aplicación pueda aparecer en el mercado de aplicaciones.
`auth`*	Objeto	Un objeto que contiene los detalles del método de autenticación de la aplicación. Consulta la tabla de autenticación para más detalles.
`permittedUrls`	Objeto	Una matriz que contiene las URL a las que la aplicación puede llamar. Las URL deben utilizar el esquema HTTPS y deben contener una autoridad, seguida de un prefijo de ruta opcional si es necesario.
`supportEmail`	Cadena	Una dirección de correo electrónico válida con la que los usuarios puedan ponerse en contacto para recibir asistencia.
`documentationUrl`	Cadena	La URL externa a la que los usuarios pueden navegar para obtener documentación de apoyo. Debe utilizar HTTPS.
`supportUrl`	Cadena	La URL externa a la que los usuarios pueden navegar para obtener asistencia adicional. Debe utilizar HTTPS.
`supportPhone`	Cadena	El número de teléfono al que pueden dirigirse los usuarios para solicitar asistencia. Debe empezar por el signo más (`+`).

campos de autenticación

Los campos marcados con * son obligatorios.

Campo	Tipo	Descripción
`type`*	Cadena	El tipo de autenticación. Debe estar configurado como `oauth` para que la aplicación utilice la autenticación con OAuth.
`redirectUrls`*	Matriz	Lista de URL a las que el proceso de OAuth puede redirigir. Cada aplicación debe tener al menos una URL de redireccionamiento de autenticación, y debe utilizar HTTPS. La única excepción es que se permite `http://localhost` para las pruebas.
`requiredScopes`*	Matriz	Una lista de los permisos necesarios para tu aplicación. Cada aplicación debe incluir al menos un permiso, y el usuario que la instala debe conceder estos permisos para que la aplicación se instale correctamente. Más información sobre los permisos a continuación.
`optionalScopes`	Matriz	Una lista de los permisos opcionales de tu aplicación. Estos permisos pueden excluirse de la autorización durante la instalación si la cuenta o el usuario que instala la aplicación no tiene los permisos adecuados. En ese caso, el permiso no se incluirá en el token de actualización o de acceso resultante. Más información sobre los permisos abajo.
`conditionallyRequiredScopes`	Matriz	Lista de permisos que solo son necesarios cuando se incluyen en el parámetro de consulta `scope` de la URL de instalación. Más información sobre los permisos abajo.

Permisos

En el campo auth del archivo de configuración de una aplicación, puedes especificar tres tipos de permisos: permisos requeridos, permisos requeridos condicionalmente y permisos opcionales. Para esta etapa de la beta, solo debes incluir los permisos de los objetos de tu aplicación como conditionallyRequiredScopes. Esto te permitirá aislar tus nuevas funciones para clientes específicos incluyendo los permisos de los objetos de la aplicación en la URL de instalación. Los permisos de los objetos de la aplicación utilizan el siguiente formato: crm.app.schemas.<appObjectFullyQualifiedName>.read Por ejemplo, para un objeto de aplicación con el FQN a16858319_cars, el permiso read sería: crm.app.schemas.a16858319_cars.read. Como mínimo, tu aplicación debe incluir el permiso read de arriba para que los clientes puedan acceder al objeto. Se recomienda incluir todos los permisos de objetos de aplicación en tu aplicación, como se muestra abajo.

"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": []
    },

Para obtener una lista completa de los permisos disponibles, consulta la referencia de permisos.

Definición del componente de webhooks

Para definir un conjunto de suscripciones a webhook para tu aplicación, incluye un directorio webhooks en el proyecto, junto con un archivo de configuración *-hsmeta.json.

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

Abajo se indican las opciones de configuración disponibles para el archivo *-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 *-hsmeta.json campos

Los campos marcados con * son obligatorios.

Campo	Tipo	Descripción
`uid`*	Cadena	Un identificador único interno para el componente webhook.
`type`*	Cadena	El tipo de componente, que en este caso debe ser `webhooks`.
`settings`*	Objeto	Un objeto que especifica dos campos: `targetUrl`, que es la URL disponible públicamente para que HubSpot llame a donde se entregarán las cargas de eventos, y `maxConcurrentRequests`, que es el límite de peticiones HTTP que HubSpot realizará en un período determinado.
`subscriptions`*	Objeto	Un objeto que especifica los tipos de suscripción a los que se suscribirá tu aplicación.
`crmObjects`	Matriz	Matriz que contiene definiciones de suscripción a eventos. Esta es la matriz estándar que hay que incluir, y debe utilizarse para todos los eventos en el nuevo formato (`object.*`). En cambio, los tipos de suscripción webhook clásicos deben incluirse en las matrices `legacyCrmObjects` y `hubEvents`, dependiendo del evento.
`legacyCrmObjects`	Matriz	Matriz que contiene tipos de suscripción clásicos, como `contact.creation` y `deal.deletion`.
`hubEvents`	Matriz	Matriz que contiene los tipos de suscripción clásicos `contact.privacyDeletion` y `conversation.*`

Para cada objeto subscription, se pueden especificar los siguientes campos, en función del tipo de definición de suscripción al que estés suscrito (es decir, crmObjects, legacyCrmObjects o hubEvents) o de si estás suscrito a un cambio de propiedad específico (por ejemplo, contact.propertyChange).

Campo	Tipo	Descripción
`subscriptionType`	Cadena	El tipo de evento al que se está suscrito.
`objectType`	Cadena	Para las suscripciones especificadas en la matriz `crmObjects`, especifica el objeto del CRM al que se está suscribiendo tu aplicación. Para suscribirte a los cambios de un objeto de aplicación, incluye el nombre de tu objeto de aplicación para este campo (por ejemplo, `car_app_object`).
`propertyName`	Cadena	Para las suscripciones de cambio de propiedad, especifica qué propiedad desencadenará el evento de webhook.
`active`	Booleano	Si se desencadenarán eventos de webhook para esta suscripción.

Esquema de la tarjeta de la aplicación

Para crear una tarjeta de aplicación que aparezca en una página de registro de objetos de aplicación, incluye un directorio de componentes cards en el proyecto, junto con un archivo de configuración.

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

Asegúrate de que has ejecutado hs project upload después de crear tu componente de objeto de aplicación y los archivos de configuración asociados.
En tu archivo my-app-card-hsmeta.json, agrega el UID del objeto de tu aplicación a la matriz objectTypes (por ejemplo, "app_object_uid" en este ejemplo). Cada uno de los campos disponibles en el archivo .json se detalla en la tabla siguiente.

Resumen de cambios

Ten en cuenta los siguientes cambios en los archivos de configuración de las tarjetas de aplicación:

Agregados los campos de nivel superior uid, type y config.
El campo module ha pasado a llamarse entrypoint.
El campo title ha pasado a llamarse name.
El campo objectTypes se ha simplificado para aceptar una matriz de cadenas.

{
  "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"]
  }
}

Cuando hayas guardado los cambios en tu archivo example-card-hsmeta.json, ejecuta hs project upload.

Las tarjetas se agregan automáticamente a la vista predeterminada de los objetos de la aplicación. Si la tarjeta no aparece automáticamente, aprende a agregar tarjetas a los registros de CRM.

Ver ejemplo en GitHub

Tarjeta de aplicación *-hsmeta.json campos

Los campos marcados con * son obligatorios.

Campo	Tipo	Descripción
`uid`*	Cadena	El identificador único de la tarjeta. Puede ser cualquier cadena, pero debe identificar significativamente a la tarjeta. HubSpot identificará la tarjeta por este ID para que puedas cambiar el título de la tarjeta sin eliminar datos históricos o de estado, como la posición en el registro del CRM.
`type`	Cadena	El tipo de componente, que en este caso debe ser `card`.
`config`	Objeto	Un objeto que contiene detalles de configuración.
`name`*	Cadena	El título de la tarjeta, tal y como se muestra en la interfaz de usuario de HubSpot.
`description`	Cadena	Descripción de la tarjeta.
`previewImage`	Objeto	Objeto que contiene los campos `file` y `altText`. El campo `file` es la ruta relativa a la imagen de previsualización. Las extensiones de archivo válidas son png, jpeg, jpg o gif. El tamaño máximo del archivo es de 5.0 MB. El campo `altText` es una breve descripción de la imagen.
`entrypoint`*	Cadena	La ruta del archivo del código React del front-end de la tarjeta.
`location`*	`crm.record.tab` \| `crm.record.sidebar` \| `helpdesk.sidebar`	Dónde aparece la tarjeta en la interfaz de usuario de HubSpot. Más información sobre la ubicación de la extensión.
`objectTypes`*	Matriz	Los tipos de registros del CRM en los que aparecerá la tarjeta.

Asociaciones de objetos de la aplicación

Para habilitar las asociaciones entre el objeto de tu aplicación y otros objetos del CRM, incluye un directorio de componentes app-object-associations en el proyecto, junto con un archivo de configuración.

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

Abajo se indican las opciones de configuración del objeto de la aplicación disponibles (*-association-hsmeta.json).

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

Asociación *-asociación-hsmeta.json campos

Los campos marcados con * son obligatorios.

Campo	Tipo	Descripción
`uid`*	Cadena	Un identificador único interno para la aplicación. Debe ser globalmente único dentro del proyecto.
`type`*	Cadena	El tipo de componente. Debe coincidir con el nombre de la carpeta primaria (`app-object-association`).
`config`*	Objeto	Objeto que contiene la configuración de la asociación de objetos.
`firstObjectType`*	Cadena	El primer objeto de la asociación. Puede ser un objeto de aplicación o un objeto del CRM de HubSpot. Se hace referencia a los objetos de la aplicación por su `uid` especificado en su archivo fuente. Los objetos estándar se denominan por su `fullyQualifiedName`. La asociación resultante será bidireccional, por lo que el orden de los valores de estos campos es arbitrario.
`secondObjectType`*	Cadena	El segundo objeto de la asociación. Consulta `firstObjectType` para más detalles.

Crear aplicaciones

Agregar funciones

Publicar en el mercado de HubSpot

Referencia de objetos de aplicación (BETA)

Estructura del proyecto

Ver ejemplo en GitHub

Objetos de aplicación

Ver ejemplo en GitHub

Esquema de la aplicación

Ver ejemplo en GitHub

Esquema de la aplicación *-hsmeta.json campos

campos de autenticación

Permisos

Definición del componente de webhooks

Webhook *-hsmeta.json campos

Esquema de la tarjeta de la aplicación

Ver ejemplo en GitHub

Tarjeta de aplicación *-hsmeta.json campos

Asociaciones de objetos de la aplicación

Asociación *-asociación-hsmeta.json campos

​Estructura del proyecto

Ver ejemplo en GitHub

​Objetos de aplicación

Ver ejemplo en GitHub

​Esquema de la aplicación

Ver ejemplo en GitHub

​Esquema de la aplicación *-hsmeta.json campos

​campos de autenticación

​Permisos

​Definición del componente de webhooks

​Webhook *-hsmeta.json campos

​Esquema de la tarjeta de la aplicación

Ver ejemplo en GitHub

​Tarjeta de aplicación *-hsmeta.json campos

​Asociaciones de objetos de la aplicación

​Asociación *-asociación-hsmeta.json campos

Estructura del proyecto

Objetos de aplicación

Esquema de la aplicación

Esquema de la aplicación *-hsmeta.json campos

campos de autenticación

Permisos

Definición del componente de webhooks

Webhook *-hsmeta.json campos

Esquema de la tarjeta de la aplicación

Tarjeta de aplicación *-hsmeta.json campos

Asociaciones de objetos de la aplicación

Asociación *-asociación-hsmeta.json campos