Пакет позволяет запустить приложение на основе React, интегрированное с Zendesk App Framework (ZAF), и позволяет быстро приступить к разработке приложений для Zendesk Sell.
Примечание. Документация основана на Руководстве разработчика Zendesk. Они содержат только избранную и, надеемся, самую необходимую информацию с точки зрения создания приложения, интегрированного с Zendesk Sell. Если у вас с чем-то возникли проблемы или здесь недостаточно информации, посетите актуальную документацию.
Для успешной установки приложения в продукт Zendesk в приложение необходимо включить следующую структуру папок и файлы:
assets/
logo.png
logo-small.png
translations/
en.json
manifest.json
Ниже приведены краткие описания необходимых файлов:
Пример манифеста приложения 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 "
}
} Вы должны указать, где вы хотите, чтобы ваше приложение отображалось в каждом интерфейсе продукта, с помощью свойства location в файле Manifest.json. Местоположение — это место, где в продукте могут появляться iframe. Вы можете указать одно или несколько местоположений в одном или нескольких продуктах Zendesk. По умолчанию ваше приложение будет доступно в Zendesk Sell на всех карточках объектов (Лид, Контакт, Сделка) на панели справа.
"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 "
}
}
}Доступные местоположения см. в разделе API для продажи приложений. Чтобы узнать больше о настройке местоположения приложения, посетите раздел «Настройка местоположения приложения» в руководстве разработчика.
Когда приложение отправляет запросы AJAX, настройки запроса можно просмотреть в консоли браузера. Некоторые настройки могут содержать конфиденциальную информацию, например ключ API или токен. Рекомендуемый способ предотвратить такое поведение — использовать OAuth Authentication . Другой вариант — использование Secure Settings . Выбирайте любой вариант, который вам больше всего подходит.
Вы можете использовать OAuth2 для аутентификации всех ваших запросов API к внешней службе. OAuth предоставляет вашему приложению безопасный способ доступа к данным вашей учетной записи, не требуя отправки конфиденциальной информации, такой как имена пользователей и пароли, вместе с запросами. Чтобы использовать аутентификацию OAuth, вам необходимо зарегистрировать свое приложение в сторонней службе, чтобы сгенерировать учетные данные OAuth для вашего приложения. Вам также необходимо добавить в приложение некоторые функции для реализации потока авторизации OAuth.
При регистрации приложения вам будет представлен экран с настройками вашего нового приложения, включая имя приложения, описание и другую информацию о приложении, которую вам необходимо заполнить. Кроме того, вы также найдете настройки аутентификации для ваше приложение, например идентификатор клиента, секрет клиента, URL-адрес перенаправления, а также области, используемые вашим приложением. Эти элементы понадобятся вам при инициализации соединения OAuth между вашим приложением и сторонней службой.
Client ID . Этот идентификатор уникален для вашего приложения и используется для запуска OAuth.Client secret — используется для установления и обновления аутентификации OAuth.Redirect URL — пользователи будут перенаправлены в это место после предоставления доступа к вашему приложению. Используйте один из следующих URL-адресов:Scope — дополнительная мера безопасности. Область определяет, к каким данным ваше приложение имеет разрешение на доступ.OAuth URL . Этот URL-адрес понадобится пользователю для подключения к вашему приложению. URL-адрес создается на основе учетных данных клиента вашего приложения, URL-адреса перенаправления и конфигурации областей. Используйте Client ID и Client secret в своем приложении, как описано в следующем разделе.
После регистрации приложения вам необходимо определить настройки OAuth в файле manifest.json . Обновите client_id и client_secret на свои.
"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 "
}Также в список параметров необходимо добавить параметр типа «oauth»:
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
]Для получения дополнительной информации посетите документацию
В коде вашего приложения используйте заполнитель {{setting.access_token}} и свойство secure: true чтобы выполнить запрос 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 ( ... ) ; Это API только для JSON. Вы должны предоставить заголовок Content-Type: application/json для запросов PUT и POST. Вы должны установить заголовок Accept: application/json для всех запросов.
var settings = {
url : 'https://www.example.com/api/user' ,
dataType : 'json' ,
contentType : 'application/json' ,
...
} ; Настройки безопасности — это еще один способ сделать настройки недоступными для агентов при отправке запросов AJAX. Значения параметров вставляются только на стороне сервера исходящего запроса на уровне прокси. См. Использование настроек безопасности для их настройки.
Хотя вы можете использовать любой собственный CSS или интерфейсную среду для внешнего вида вашего приложения, Zendesk рекомендует использовать Zendesk Garden. Zendesk Garden задуман как общая основа стилей и компонентов для всех продуктов Zendesk. Чтобы ваше приложение соответствовало внешнему виду Zendesk, по умолчанию в нем используется Zendesk Garden.
Пример:
. YourElement {
color : var ( --zd-color-green-600 );
padding : var ( --zd-spacing-sm );
}Дополнительную информацию о классах CSS и компонентах React в Zendesk Garden см. на сайте Garden.zendesk.com.
Клиент ZAF позволяет вашему приложению в iframe взаимодействовать с хост-продуктом Zendesk. Вы можете использовать клиент в своих приложениях для прослушивания событий, вызова действий и доступа к свойствам в каждом месте. См. руководство по клиентскому API ZAF.
Пример:
const client = ZAFClient . init ( )
client . get ( 'contact.email' ) . then ( function ( data ) {
console . log ( data ) // { "contact.email": "[email protected]" }
} )Пакет @zendesk/sell-zaf-app-toolbox предоставляет множество полезных методов, хуков и компонентов, которые помогут вам создавать приложения React, интегрированные с Zendesk Sell, быстрее и с меньшими усилиями. Под капотом они используют App Framework Client от Zendesk. Чтобы узнать больше, посетите репозиторий.
Используйте интерфейс командной строки и перейдите к папке, содержащей приложение, которое вы хотите протестировать.
При необходимости установите зависимости:
npm installЗапустите свое приложение с помощью следующей команды:
npm startОткройте новое окно в терминале и запустите сервер:
npm run server
В браузере перейдите на страницу продукта, на которой вы указали, что приложение будет отображаться (например, карточка сделки/лида/контакта), и добавьте ?zcli_apps=true к URL-адресу. Пример:
https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true
В адресной строке браузера щелкните значок щита справа (Chrome) или значок замка слева (Firefox) и согласитесь загрузить небезопасный скрипт (Chrome) или отключить защиту (Firefox).
Примечание. В Safari нет возможности отключить защиту.
Чтобы проверить и автоматически исправить некоторые ошибки, выполните:
npm run lintЧтобы отформатировать код:
npm run prettierСоберите пакет с минифицированными исходниками:
npm run build Команда создает новый файл .zip в dist/tmp . Теперь ваше приложение готово к установке в качестве частного приложения в Zendesk Sell!
Integrations , а затем выберите вкладку Apps .Upload private app .dist/tmp в локальный проект приложения.Если ваше приложение использует OAuth или настройки безопасности, вы можете продолжить тестирование его локально после удаленной установки.
zcli.apps.config.jsonplan и paramters ). {
"plan" : " silver " ,
"app_id" : YOUR_APP_ID,
"parameters" : {}
} Чтобы найти идентификатор установки приложения, войдите в свой экземпляр Zendesk Sell в качестве администратора и откройте следующую страницу в том же браузере, заменив your_subdomain своим собственным:
https://your_subdomain.zendesk.com/api/sell/apps/installations.json (в рабочей версии)
Найдите установленное приложение и запишите его значение id , а не значение app_id .
