El paquete le permite iniciar una aplicación basada en React, que está integrada con Zendesk App Framework (ZAF), y le permite comenzar rápidamente a desarrollar aplicaciones para Zendesk Sell.
Nota: Los documentos se basan en Zendesk Developer Guide. Contienen solo información seleccionada y, con suerte, la más necesaria en términos de creación de una aplicación integrada con Zendesk Sell. Si tiene problemas con algo o no hay suficiente información aquí, visite la documentación real.
Se deben incluir la siguiente estructura de carpetas y archivos en una aplicación para instalarla correctamente en un producto Zendesk:
assets/
logo.png
logo-small.png
translations/
en.json
manifest.json
Las siguientes son breves descripciones de los archivos requeridos:
Ejemplo de manifiesto de aplicación de HubSpot for Sell:
{
"name" : " Hubspot " ,
"author" : {
"name" : " Zendesk " ,
"email" : " [email protected] " ,
"url" : " https://www.zendesk.com "
},
"defaultLocale" : " en " ,
"private" : false ,
"singleInstall" : true ,
"location" : {
"sell" : {
"lead_card" : {
"url" : " assets/index.html "
},
"person_card" : {
"url" : " assets/index.html "
},
"company_card" : {
"url" : " assets/index.html "
}
}
},
"version" : " 2.0.3 " ,
"frameworkVersion" : " 2.0 " ,
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
],
"oauth" : {
"client_id" : " {Client ID} " ,
"client_secret" : " {Client Secret} " ,
"authorize_uri" : " https://app.hubspot.com/oauth/authorize " ,
"access_token_uri" : " https://api.hubapi.com/oauth/v1/token " ,
"scope" : " contacts content oauth "
}
} Debe declarar dónde desea que aparezca su aplicación en cada interfaz de producto con la propiedad location en manifest.json. Las ubicaciones son donde pueden aparecer los iframes en el producto. Puede especificar una o más ubicaciones en uno o más productos Zendesk. De forma predeterminada, su aplicación estará disponible en Zendesk Sell en todas las tarjetas de objeto (Prospecto, Contacto, Trato) en el panel del lado derecho.
"location" : {
"sell" : {
"lead_card" : {
"url" : " assets/index.html "
},
"person_card" : {
"url" : " assets/index.html "
},
"company_card" : {
"url" : " assets/index.html "
},
"deal_card" : {
"url" : " assets/index.html "
}
}
}Para conocer las ubicaciones disponibles, consulte API de venta de aplicaciones. Para obtener más información sobre cómo configurar la ubicación de la aplicación, visite la sección Configuración de la ubicación de la aplicación en la guía para desarrolladores.
Cuando una aplicación realiza solicitudes AJAX, la configuración de la solicitud se puede ver en la consola del navegador. Algunas configuraciones pueden contener información confidencial, como una clave API o un token. Una forma recomendada de evitar este comportamiento es utilizar OAuth Authentication . La otra opción puede ser utilizar Secure Settings . Elige la opción que más te convenga.
Puede utilizar OAuth2 para autenticar todas sus solicitudes de API en un servicio externo. OAuth proporciona una forma segura para que su aplicación acceda a los datos de su cuenta sin necesidad de enviar información confidencial como nombres de usuario y contraseñas con las solicitudes. Para utilizar la autenticación OAuth, debe registrar su aplicación con un servicio de terceros para generar credenciales OAuth para su aplicación. También necesita agregar alguna funcionalidad a su aplicación para implementar un flujo de autorización OAuth.
Al registrar una aplicación, se le presentará una pantalla que muestra la configuración de su nueva aplicación, incluido el nombre de la aplicación, la descripción y otra información de la aplicación que debe completar. Además, también encontrará la configuración de autenticación para su aplicación, como el ID del cliente, el secreto del cliente, la URL de redireccionamiento, así como los alcances utilizados por su aplicación. Necesitará estos elementos al iniciar una conexión OAuth entre su aplicación y un servicio de terceros.
Client ID : este ID es exclusivo de su aplicación y se utiliza para iniciar OAuth.Client secret : se utiliza para establecer y actualizar la autenticación OAuth.Redirect URL : los usuarios serán redirigidos a esta ubicación después de otorgarles acceso a su aplicación. Utilice una de las siguientes URL:Scope - Medida de seguridad opcional. El alcance determina a qué datos tiene permiso de acceso su aplicación.OAuth URL : un usuario necesitará esta URL para conectar su aplicación. La URL se construye en función de las credenciales del cliente de su aplicación, la URL de redireccionamiento y la configuración de alcances. Utilice la Client ID y el Client secret en su aplicación como se describe en la siguiente sección.
Una vez que haya registrado su aplicación, debe definir la configuración de OAuth en el archivo manifest.json . Actualice client_id y client_secret con el suyo.
"oauth" : {
"client_id" : " {Client ID} " ,
"client_secret" : " {Client Secret} " ,
"authorize_uri" : " https://app.hubspot.com/oauth/authorize " ,
"access_token_uri" : " https://api.hubapi.com/oauth/v1/token " ,
"scope" : " contacts content oauth "
}También necesitas agregar un parámetro de tipo "oauth" a la lista de parámetros:
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
]Para obtener más información, visite los documentos.
En el código de su aplicación, use el marcador de posición {{setting.access_token}} y una propiedad secure: true para realizar una solicitud OAuth.
var settings = {
url : 'https://www.example.com/api/user' ,
headers : { "Authorization" : "Bearer {{setting.access_token}}" } ,
secure : true ,
type : 'GET'
} ;
var client = ZAFClient . init ( ) ;
client . request ( settings ) . then ( ... ) ; Esta es una API solo JSON. Debe proporcionar un encabezado Content-Type: application/json en las solicitudes PUT y POST. Debe establecer un encabezado Accept: application/json en todas las solicitudes.
var settings = {
url : 'https://www.example.com/api/user' ,
dataType : 'json' ,
contentType : 'application/json' ,
...
} ; La configuración segura es otra forma de hacer que la configuración sea inaccesible para los agentes al realizar solicitudes AJAX. Los valores de configuración se insertan solo en el lado del servidor de la solicitud saliente en la capa de proxy. Consulte Uso de configuraciones seguras para configurarlas.
Si bien puedes usar cualquier CSS personalizado o marco de front-end para la apariencia de tu aplicación, Zendesk recomienda usar Zendesk Garden. Zendesk Garden está diseñado para ser una base común de estilos y componentes entre todos los productos Zendesk. Para que su aplicación coincida con la apariencia de Zendesk, Zendesk Garden se utiliza en la aplicación de forma predeterminada.
Ejemplo:
. YourElement {
color : var ( --zd-color-green-600 );
padding : var ( --zd-spacing-sm );
}Para obtener más información sobre las clases CSS y los componentes de React en Zendesk Garden, consulte garden.zendesk.com.
El cliente ZAF permite que su aplicación en el iframe se comunique con el producto anfitrión de Zendesk. Puede utilizar el cliente en sus aplicaciones para escuchar eventos, invocar acciones y acceder a propiedades en cada ubicación. Consulte la guía API del cliente ZAF.
Ejemplo:
const client = ZAFClient . init ( )
client . get ( 'contact.email' ) . then ( function ( data ) {
console . log ( data ) // { "contact.email": "[email protected]" }
} )El paquete @zendesk/sell-zaf-app-toolbox ofrece una gran cantidad de métodos, ganchos y componentes útiles que lo ayudan a crear aplicaciones React integradas con Zendesk Sell más rápido y con menos esfuerzo. Usan App Framework Client de Zendesk bajo el capó. Para saber más visita el repositorio.
Utilice su interfaz de línea de comandos para navegar hasta la carpeta que contiene la aplicación que desea probar.
Instale dependencias si es necesario:
npm installInicie su aplicación con el siguiente comando:
npm startAbra una nueva ventana en su terminal e inicie el servidor:
npm run server
En un navegador, navegue hasta la página del producto donde especificó que aparezca la aplicación (por ejemplo, oferta/cliente potencial/tarjeta de contacto) y agregue ?zcli_apps=true a la URL. Ejemplo:
https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true
En la barra de direcciones de su navegador, haga clic en el icono de escudo a la derecha (Chrome) o en el icono de candado a la izquierda (Firefox) y acepte cargar un script no seguro (Chrome) o desactivar la protección (Firefox).
Nota: Safari no tiene ninguna opción para desactivar la protección.
Para eliminar pelusa y corregir automáticamente algunos errores, ejecute:
npm run lintPara formatear su código:
npm run prettierCree un paquete con fuentes minimizadas:
npm run build El comando crea un nuevo archivo .zip en dist/tmp . ¡Ahora su aplicación está lista para instalarse como una aplicación privada en su Zendesk Sell!
Integrations y luego seleccione la pestaña Apps .Upload private app .dist/tmp en su proyecto de aplicación local.Si su aplicación utiliza OAuth o configuraciones seguras, puede seguir probándola localmente después de instalarla de forma remota.
zcli.apps.config.jsonplan y paramters ). {
"plan" : " silver " ,
"app_id" : YOUR_APP_ID,
"parameters" : {}
} Para encontrar la identificación de instalación de la aplicación, inicie sesión en su instancia de Zendesk Sell como administrador y abra la siguiente página en el mismo navegador, reemplazando your_subdomain con el suyo:
https://your_subdomain.zendesk.com/api/sell/apps/installations.json (en producción)
Localice su aplicación instalada y anote su valor id , no su valor de app_id .
