> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.es/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Referencia de tarjetas de aplicación (BETA)
> Información de referencia para crear tarjetas de aplicación en la última versión de la plataforma para desarrolladores.
A continuación, encontrarás información de referencia para crear tarjetas de aplicación
## Estructura del proyecto
En el contexto de un proyecto, los componentes de las tarjetas de aplicación se definen en un directorio `cards` dentro de `app/`. El directorio `cards` debe contener:
* Un archivo de definición del esquema JSON para cada tipo de tarjeta (`*-hsmeta.json`).
* Un archivo React que renderiza la interfaz de la tarjeta. Puede ser un archivo `.jsx` o `.tsx`.
* Un archivo `package.json` para gestionar las dependencias necesarias.
```shell theme={null}
project-folder/
└── src/
└── app/
├── app-hsmeta.json
└── cards/
└── my-app-card-hsmeta.json
└── my-app-card.jsx
└── package.json
```
## Esquema de la tarjeta de aplicación
En el archivo de configuración `*-hsmeta.json` de tu tarjeta de aplicación, incluye las siguientes propiedades.
```json theme={null}
{
"uid": "example-card",
"type": "card",
"config": {
"name": "Hello Example App",
"description": "A description of the card's purpose.",
"location": "crm.record.tab",
"entrypoint": "/app/cards/ExampleCard.jsx",
"objectTypes": ["contacts"]
}
}
```
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 de la interfaz de la tarjeta. |
| `location`\* | `crm.record.tab` \| `crm.record.sidebar` \| `crm.preview` \|`helpdesk.sidebar` | Dónde aparece la tarjeta en la interfaz de usuario de HubSpot. Solo puedes especificar un valor de ubicación, pero algunas combinaciones de `location` y `objectTypes` dan lugar a un soporte de ubicación múltiple. Para más información, consulta la sección [*Localizaciones compatibles*](#supported-locations). |
| `objectTypes`\* | Matriz | Los tipos de registros del CRM en los que aparecerá la tarjeta. Para más detalles, consulta la sección [*Objetos compatibles*](#supported-objects). |
### Objetos compatibles
En la matriz `objectTypes` del archivo de configuración `*-hsmeta.json` de la tarjeta, especifica los tipos de registros del CRM en los que aparecerá la tarjeta. A continuación se indican los objetos del CRM admitidos actualmente, su valor `objectType` y el [permiso](/apps/legacy-apps/public-apps/overview#scope-types) mínimo que debes agregar a tu aplicación.
Para los objetos estándar de HubSpot, los valores de `objectType` no distinguen entre mayúsculas y minúsculas, y admiten tanto el singular como el plural. Por ejemplo, tanto `"CONTACT"` como `"contacts"` son válidos.
| Objeto del CRM | objectType valor | Permiso relacionado |
| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Contactos | `CONTACT` | `crm.objects.contacts.read` |
| Empresas | `COMPANY` | `crm.objects.companies.read` |
| Negocios | `DEALS` | `crm.objects.deals.read` |
| Tickets | `TICKETS` | `tickets` |
| Objetos personalizados | `p_objectName` (distingue mayúsculas de minúsculas) | `crm.objects.custom.read` |
| Objetos de la aplicación | `app_object_uid` | Ver [permisos de los objetos de la aplicación](/apps/developer-platform/add-features/app-objects/reference#scopes) |
Además, los siguientes objetos del CRM son compatibles si se han [activado en la biblioteca de objetos](https://knowledge.hubspot.com/data-management/use-the-data-model-builder):
| Objeto del CRM | objectType valor | Permisos relacionados |
| -------------- | ---------------- | ------------------------------- |
| Citas | `APPOINTMENTS` | `crm.objects.appointments.read` |
| Cursos | `COURSES` | `crm.objects.courses.read` |
| Listados | `LISTINGS` | `crm.objects.listings.read` |
| Servicios | `SERVICES` | `crm.objects.services.read` |
### Ubicaciones compatibles
En el campo `location` del archivo de configuración `*-hsmeta.json` de la tarjeta, especifica dónde debe mostrarse la tarjeta en HubSpot. A continuación se indican las ubicaciones admitidas actualmente.
* `crm.record.tab`: coloca la extensión en la columna central de las páginas de registros del CRM, en una de las pestañas predeterminadas de HubSpot o en una pestaña personalizada. Si `objectType` está configurado como `COMPANIES`, la tarjeta también estará disponible en el [panel de vista previa de cuentas objetivo del espacio de ventas](https://knowledge.hubspot.com/prospecting/manage-companies-in-the-sales-workspace).
Si has personalizado la columna central previamente, tendrás que [personalizar la vista de la columna central](https://knowledge.hubspot.com/object-settings/customize-records) para hacer visibles las extensiones recién creadas.
* `crm.record.sidebar`: muestra la extensión en la barra lateral derecha de las páginas de registro del CRM. Las extensiones de la barra lateral no pueden utilizar [componentes de datos del CRM](/apps/developer-platform/add-features/ui-extensibility/ui-components/crm-data-components/overview). Si `objectType` está configurado como `DEALS`, la tarjeta también estará disponible en la [barra lateral de negocios del espacio de ventas](https://knowledge.hubspot.com/prospecting/create-and-manage-deals-in-the-sales-workspace).
* `crm.preview`: muestra la tarjeta de la aplicación en el panel de vista previa al que puedes acceder en todo el CRM. Cuando utilices esta ubicación, la extensión estará disponible al previsualizar el `objectTypes` especificado en el [archivo de configuración JSON](#example-card-json). Esto incluye la previsualización de registros desde las páginas de registros del CRM, páginas de índice, vistas de tablero y la herramienta de listas. Más información sobre cómo [personalizar las vistas previas](https://knowledge.hubspot.com/object-settings/customize-record-previews).
* `helpdesk.sidebar`: muestra la tarjeta en las barras laterales del ticket dentro del centro de ayuda. Esto incluye tanto el panel de vista previa del ticket en la página de inicio del centro de ayuda como la barra lateral derecha de la visualización del ticket en el centro de ayuda. Para agregar una tarjeta a esta ubicación, tendrás que [configurar los ajustes de tu centro de ayuda](https://knowledge.hubspot.com/help-desk/customize-the-right-sidebar-of-help-desk) para incluir la tarjeta.
Al crear una extensión para esta ubicación, también tendrás que asegurarte de que el [archivo de configuración JSON de la aplicación](/apps/developer-platform/build-apps/app-configuration) incluye `tickets` en la matriz de `scopes`, y de que el [archivo de configuración JSON de la tarjeta](#app-card-schema) incluye `tickets` en el campo `objectTypes`.
* Página principal del centro de ayuda:
* Vista del ticket del centro de ayuda:
## Crear la interfaz de React
La interfaz de usuario de una tarjeta de aplicación se crea mediante un archivo de componentes React, ya sea `.jsx` o `.tsx`. Este archivo se encuentra en el directorio `cards/` junto al [archivo JSON de configuración de la tarjeta](#app-card-schema) (`*-hsmeta.json`). En el archivo de configuración de la tarjeta, especificarás la ruta del archivo React en el campo `entrypoint`.
Abajo se muestra un ejemplo de una tarjeta de aplicación sencilla, que incluye los [componentes de interfaz de usuario](/apps/developer-platform/add-features/ui-extensibility/ui-components/overview) `Text` y `Button` para representar el contenido de la tarjeta, junto con un componente `Flex` para gestionar el diseño.
```jsx theme={null}
import React from "react";
import { Text, Button, Flex, hubspot } from "@hubspot/ui-extensions";
// Define the extension to be run within the Hubspot CRM
hubspot.extend(() => );
// Define the Extension component
const Extension = () => {
return (
This is a simple getting started UI extension with static text.
);
};
```
Se proporciona la siguiente documentación de referencia para crear el aspecto y la funcionalidad de las tarjetas:
* [Documentación de referencia de los componentes de ampliación de la interfaz de usuario](/apps/developer-platform/add-features/ui-extensibility/ui-components/overview)
* [SDK de extensiones de IU](/apps/developer-platform/add-features/ui-extensibility/ui-extensions-sdk)
## Gestionar las dependencias
Puedes incluir dependencias para tu tarjeta de aplicación en un archivo `package.json` dentro del directorio `cards/`. Por defecto, al agregar una tarjeta de aplicación mediante el comando `hs project add`, se te creará un archivo `package.json` con las siguientes dependencias:
* `@hubspot/ui-extensions`
* `react`
* `typescript`
Para instalar las dependencias de los componentes del proyecto con un archivo `package.json`, puedes ejecutar el comando `hs project install-deps` en el directorio de tu proyecto.
```json theme={null}
{
"name": "hubspot-example-extension",
"version": "0.1.0",
"license": "MIT",
"dependencies": {
"@hubspot/ui-extensions": "latest",
"react": "^18.2.0"
},
"devDependencies": {
"typescript": "^5.3.3"
}
}
```