이 패키지를 사용하면 ZAF(Zendesk App Framework)와 통합된 React 기반 애플리케이션을 부트스트랩할 수 있으며 Zendesk Sell용 앱 개발을 빠르게 시작할 수 있습니다.
참고: 이 문서는 Zendesk 개발자 가이드를 기반으로 합니다. 여기에는 Zendesk Sell과 통합된 앱을 만드는 데 가장 필요한 정보만 선택되어 포함되어 있습니다. 문제가 있거나 여기에 정보가 충분하지 않은 경우 실제 설명서를 방문하세요.
Zendesk 제품에 앱을 성공적으로 설치하려면 다음 폴더 구조와 파일이 앱에 포함되어 있어야 합니다.
assets/
logo.png
logo-small.png
translations/
en.json
manifest.json
다음은 필수 파일에 대한 간략한 설명입니다.
Sell 앱 매니페스트를 위한 HubSpot의 예:
{
"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 "
}
} 매니페스트.json의 location 속성을 사용하여 각 제품 인터페이스에서 앱을 표시할 위치를 선언해야 합니다. 위치는 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 "
}
}
}사용 가능한 위치는 Sell Apps API를 참조하세요. 앱 위치 설정에 대해 자세히 알아보려면 개발자 가이드의 앱 위치 설정 섹션을 참조하세요.
앱이 AJAX 요청을 하면 브라우저 콘솔에서 요청 설정을 볼 수 있습니다. 일부 설정에는 API 키나 토큰과 같은 민감한 정보가 포함될 수 있습니다. 이 동작을 방지하는 권장 방법은 OAuth Authentication 사용하는 것입니다. 다른 옵션은 Secure Settings 사용하는 것입니다. 가장 적합한 옵션을 선택하세요.
OAuth2를 사용하여 외부 서비스에 대한 모든 API 요청을 인증할 수 있습니다. OAuth는 요청과 함께 사용자 이름 및 비밀번호와 같은 민감한 정보를 전송하지 않고도 애플리케이션이 계정 데이터에 액세스할 수 있는 안전한 방법을 제공합니다. OAuth 인증을 사용하려면 타사 서비스에 애플리케이션을 등록하여 앱에 대한 OAuth 자격 증명을 생성해야 합니다. 또한 OAuth 인증 흐름을 구현하려면 애플리케이션에 일부 기능을 추가해야 합니다.
앱을 등록할 때 앱 이름, 설명, 작성해야 하는 기타 앱 정보를 포함하여 새 앱에 대한 설정을 보여주는 화면이 표시됩니다. 또한 다음에 대한 인증 설정도 확인할 수 있습니다. 클라이언트 ID, 클라이언트 비밀번호, 리디렉션 URL 및 앱에서 사용하는 범위와 같은 앱. 앱과 타사 서비스 간에 OAuth 연결을 시작할 때 이러한 항목이 필요합니다.
Client ID - 이 ID는 앱에 고유하며 OAuth를 시작하는 데 사용됩니다.Client secret - OAuth 인증을 설정하고 새로 고치는 데 사용됩니다.Redirect URL - 사용자는 앱에 대한 액세스 권한을 부여한 후 이 위치로 리디렉션됩니다. 다음 URL 중 하나를 사용하세요.Scope - 선택적 보안 조치. 범위는 앱이 액세스할 권한이 있는 데이터를 결정합니다.OAuth URL - 사용자가 앱을 연결하려면 이 URL이 필요합니다. URL은 앱의 클라이언트 자격 증명, 리디렉션 URL 및 범위 구성을 기반으로 구성됩니다. 다음 섹션에 설명된 대로 애플리케이션에서 Client ID 와 Client secret 사용하세요.
앱을 등록한 후에는 manifest.json 파일에서 OAuth 설정을 정의해야 합니다. 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 ( ... ) ; 이는 JSON 전용 API입니다. PUT 및 POST 요청에 Content-Type: application/json 헤더를 제공해야 합니다. 모든 요청에 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 );
}Zendesk Garden의 CSS 클래스 및 React 구성 요소에 대한 자세한 내용은 garden.zendesk.com을 참조하세요.
ZAF 클라이언트를 사용하면 iframe의 앱이 호스트 Zendesk 제품과 통신할 수 있습니다. 앱에서 클라이언트를 사용하여 이벤트를 수신하고, 작업을 호출하고, 각 위치의 속성에 액세스할 수 있습니다. ZAF 클라이언트 API 가이드를 참조하세요.
예:
const client = ZAFClient . init ( )
client . get ( 'contact.email' ) . then ( function ( data ) {
console . log ( data ) // { "contact.email": "[email protected]" }
} )@zendesk/sell-zaf-app-toolbox 패키지는 Zendesk Sell과 통합된 React 앱을 더 빠르고 적은 노력으로 구축하는 데 도움이 되는 다양한 유용한 방법, 후크 및 구성 요소를 제공합니다. 그들은 내부적으로 Zendesk의 App Framework Client를 사용합니다. 더 자세히 알아보려면 저장소를 방문하세요.
명령줄 인터페이스를 사용하여 테스트하려는 앱이 포함된 폴더로 이동합니다.
필요한 경우 종속성을 설치합니다.
npm install다음 명령을 사용하여 앱을 시작하십시오.
npm start터미널에서 새 창을 열고 서버를 시작합니다.
npm run server
브라우저에서 앱이 표시되도록 지정한 제품 페이지(예: 거래/리드/연락처 카드)로 이동하여 URL에 ?zcli_apps=true 추가합니다. 예:
https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true
브라우저의 주소 표시줄에서 오른쪽에 있는 방패 아이콘(Chrome) 또는 왼쪽에 있는 자물쇠 아이콘(Firefox)을 클릭하고 안전하지 않은 스크립트를 로드하거나(Chrome) 보호를 비활성화하는 데 동의합니다(Firefox).
참고: Safari에는 보호를 비활성화하는 옵션이 없습니다.
일부 오류를 린트하고 자동으로 수정하려면 다음을 실행하세요.
npm run lint코드 형식을 지정하려면 다음을 수행하세요.
npm run prettier축소된 소스로 패키지를 빌드합니다.
npm run build 이 명령은 dist/tmp 에 새 .zip 파일을 생성합니다. 이제 Zendesk Sell에 앱을 비공개 앱으로 설치할 준비가 되었습니다!
Integrations 섹션을 찾은 다음 Apps 탭을 선택합니다.Upload private app 버튼을 클릭하세요.dist/tmp 에서 최신 .zip 파일을 업로드하세요.앱이 OAuth 또는 보안 설정을 사용하는 경우 원격으로 설치한 후 로컬에서 계속 테스트할 수 있습니다.
zcli.apps.config.json 이라는 파일을 만듭니다.plan 및 paramters 키를 수정할 수도 있음). {
"plan" : " silver " ,
"app_id" : YOUR_APP_ID,
"parameters" : {}
} 앱 설치 ID를 찾으려면 Zendesk Sell 인스턴스에 관리자로 로그인하고 동일한 브라우저에서 다음 페이지를 열고 your_subdomain 자신의 도메인으로 바꾸세요.
https://your_subdomain.zendesk.com/api/sell/apps/installations.json(프로덕션 중)
설치된 앱을 찾아 app_id 값이 아닌 id 값을 기록해 두세요.
