Le package vous permet de démarrer une application basée sur React, intégrée à Zendesk App Framework (ZAF), et vous permet de démarrer rapidement le développement d'applications pour Zendesk Sell.
Remarque : la documentation est basée sur le Guide du développeur Zendesk. Ils ne contiennent que les informations sélectionnées et, espérons-le, les plus nécessaires en termes de création d'une application intégrée à Zendesk Sell. Si vous rencontrez des difficultés avec quelque chose ou s'il n'y a pas suffisamment d'informations ici, veuillez consulter la documentation actuelle.
La structure de dossiers et les fichiers suivants doivent être inclus dans une application pour que l’installation de l’application réussisse dans un produit Zendesk :
assets/
logo.png
logo-small.png
translations/
en.json
manifest.json
Voici une brève description des fichiers requis :
Exemple de manifeste d'application 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 "
}
} Vous devez déclarer où vous souhaitez que votre application apparaisse dans chaque interface de produit avec la propriété location dans manifest.json. Les emplacements correspondent aux endroits où les iframes peuvent apparaître dans le produit. Vous pouvez spécifier un ou plusieurs emplacements dans un ou plusieurs produits Zendesk. Par défaut, votre application sera disponible dans Zendesk Sell sur toutes les fiches d’objet (Lead, Contact, Deal) dans le panneau de droite.
"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 "
}
}
}Pour connaître les emplacements disponibles, consultez l’API Sell Apps. Pour en savoir plus sur la configuration de l'emplacement de l'application, consultez la section Définition de l'emplacement de l'application dans le guide du développeur.
Lorsqu'une application effectue des requêtes AJAX, les paramètres de la requête peuvent être consultés dans la console du navigateur. Certains paramètres peuvent contenir des informations sensibles telles qu'une clé API ou un jeton. Une méthode recommandée pour éviter ce comportement consiste à utiliser OAuth Authentication . L'autre option peut utiliser Secure Settings . Choisissez l'option qui vous convient le mieux.
Vous pouvez utiliser OAuth2 pour authentifier toutes vos requêtes API auprès d'un service externe. OAuth offre à votre application un moyen sécurisé d'accéder aux données de votre compte sans nécessiter l'envoi d'informations sensibles telles que les noms d'utilisateur et les mots de passe avec les demandes. Pour utiliser l'authentification OAuth, vous devez enregistrer votre application auprès d'un service tiers afin de générer les informations d'identification OAuth pour votre application. Vous devez également ajouter des fonctionnalités à votre application pour implémenter un flux d'autorisation OAuth.
Lors de l'enregistrement d'une application, un écran s'affichera affichant les paramètres de votre nouvelle application, notamment le nom de l'application, la description et d'autres informations sur l'application que vous devez remplir. De plus, vous trouverez également les paramètres d'authentification pour votre application, comme l'ID client, le secret client, l'URL de redirection, ainsi que les étendues utilisées par votre application. Vous aurez besoin de ces éléments lors du lancement d'une connexion OAuth entre votre application et un service tiers.
Client ID : cet identifiant est unique à votre application et est utilisé pour lancer OAuth.Client secret : utilisé pour établir et actualiser l'authentification OAuth.Redirect URL - Les utilisateurs seront redirigés vers cet emplacement après avoir accordé l'accès à votre application. Utilisez l'une des URL suivantes :Scope - Mesure de sécurité facultative. La portée détermine les données auxquelles votre application est autorisée à accéder.OAuth URL : un utilisateur aura besoin de cette URL pour connecter votre application. L'URL est construite en fonction des informations d'identification client de votre application, de l'URL de redirection et de la configuration des étendues. Utilisez l' Client ID et le Client secret dans votre application comme décrit dans la section suivante.
Une fois que vous avez enregistré votre application, vous devez définir les paramètres OAuth dans le fichier manifest.json . Mettez à jour client_id et client_secret avec le vôtre.
"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 "
}Vous devez également ajouter un paramètre de type « oauth » à la liste des paramètres :
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
]Pour plus d'informations, visitez la documentation
Dans le code de votre application, utilisez l'espace réservé {{setting.access_token}} et une propriété secure: true pour effectuer une requête 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 ( ... ) ; Il s'agit d'une API uniquement JSON. Vous devez fournir un en-tête Content-Type: application/json sur les requêtes PUT et POST. Vous devez définir un en-tête Accept: application/json sur toutes les requêtes.
var settings = {
url : 'https://www.example.com/api/user' ,
dataType : 'json' ,
contentType : 'application/json' ,
...
} ; Les paramètres sécurisés sont un autre moyen de rendre les paramètres inaccessibles aux agents lors des requêtes AJAX. Les valeurs de paramètre sont insérées uniquement dans la requête sortante côté serveur au niveau de la couche proxy. Consultez Utilisation des paramètres sécurisés pour les configurer.
Bien que vous puissiez utiliser n’importe quel CSS ou framework frontal personnalisé pour l’apparence de votre application, Zendesk recommande d’utiliser Zendesk Garden. Zendesk Garden est conçu pour être une base commune de styles et de composants entre tous les produits Zendesk. Pour que votre application corresponde à l’apparence de Zendesk, Zendesk Garden est utilisé par défaut dans l’application.
Exemple:
. YourElement {
color : var ( --zd-color-green-600 );
padding : var ( --zd-spacing-sm );
}Pour plus d’informations sur les classes CSS et les composants React dans Zendesk Garden, consultez garden.zendesk.com.
Le client ZAF permet à votre application dans l’iframe de communiquer avec le produit Zendesk hôte. Vous pouvez utiliser le client dans vos applications pour écouter des événements, appeler des actions et accéder aux propriétés de chaque emplacement. Consultez le guide de l'API client ZAF.
Exemple:
const client = ZAFClient . init ( )
client . get ( 'contact.email' ) . then ( function ( data ) {
console . log ( data ) // { "contact.email": "[email protected]" }
} )Le package @zendesk/sell-zaf-app-toolbox fournit un ensemble de méthodes, hooks et composants utiles qui vous aident à créer des applications React intégrées à Zendesk Sell plus rapidement et avec moins d'effort. Ils utilisent le client App Framework de Zendesk sous le capot. Pour en savoir plus, visitez le référentiel.
Utilisez votre interface de ligne de commande pour accéder au dossier contenant l'application que vous souhaitez tester.
Installez les dépendances si nécessaire :
npm installDémarrez votre application avec la commande suivante :
npm startOuvrez une nouvelle fenêtre dans votre terminal et démarrez le serveur :
npm run server
Dans un navigateur, accédez à la page du produit où vous avez spécifié que l'application doit apparaître (par exemple, transaction/prospect/carte de contact) et ajoutez ?zcli_apps=true à l'URL. Exemple:
https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true
Dans la barre d'adresse de votre navigateur, cliquez sur l'icône de bouclier à droite (Chrome) ou sur l'icône de verrouillage à gauche (Firefox) et acceptez de charger un script dangereux (Chrome) ou de désactiver la protection (Firefox).
Remarque : Safari n'a pas d'option pour désactiver la protection.
Afin de lint et de corriger automatiquement certaines erreurs, exécutez :
npm run lintPour formater votre code :
npm run prettierCréez un package avec des sources minifiées :
npm run build La commande crée un nouveau fichier .zip dans dist/tmp . Votre application est maintenant prête à être installée en tant qu’application privée dans votre Zendesk Sell !
Integrations , puis sélectionnez l'onglet Apps .Upload private app .dist/tmp dans votre projet d'application local.Si votre application utilise OAuth ou des paramètres sécurisés, vous pouvez continuer à la tester localement après l'avoir installée à distance.
zcli.apps.config.jsonplan et paramters ). {
"plan" : " silver " ,
"app_id" : YOUR_APP_ID,
"parameters" : {}
} Pour trouver l’ID d’installation de l’application, connectez-vous à votre instance Zendesk Sell en tant qu’administrateur et ouvrez la page suivante dans le même navigateur, en remplaçant your_subdomain par le vôtre :
https://votre_sous-domaine.zendesk.com/api/sell/apps/installations.json (en production)
Localisez votre application installée et notez sa valeur id , et non sa valeur app_id .
