Paket ini memungkinkan Anda melakukan bootstrap pada aplikasi berbasis React, yang terintegrasi dengan Zendesk App Framework (ZAF), dan memungkinkan Anda dengan cepat memulai pengembangan aplikasi untuk Zendesk Sell.
Catatan: Dokumen ini didasarkan pada Panduan Pengembang Zendesk. Mereka hanya berisi informasi terpilih dan semoga paling penting dalam hal membuat aplikasi yang terintegrasi dengan Zendesk Sell. Jika Anda kesulitan dengan sesuatu atau informasinya tidak cukup di sini, silakan kunjungi dokumentasi sebenarnya.
Struktur folder dan file berikut harus disertakan dalam aplikasi agar berhasil menginstal aplikasi di produk Zendesk:
assets/
logo.png
logo-small.png
translations/
en.json
manifest.json
Berikut penjelasan singkat mengenai file-file yang dibutuhkan:
Contoh manifes aplikasi HubSpot untuk Jual:
{
"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 "
}
}
Anda harus menyatakan di mana Anda ingin aplikasi Anda muncul di setiap antarmuka produk dengan properti location
di manifest.json. Lokasi adalah tempat iframe dapat muncul di produk. Anda dapat menentukan satu atau lebih lokasi di satu atau beberapa produk Zendesk. Secara default, aplikasi Anda akan tersedia di Zendesk Sell di semua kartu objek (Lead, Contact, Deal) di panel sebelah kanan.
"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 "
}
}
}
Untuk lokasi yang tersedia, lihat Sell Apps API. Untuk mengetahui lebih lanjut tentang pengaturan lokasi aplikasi, kunjungi bagian Pengaturan lokasi aplikasi di panduan pengembang.
Saat aplikasi membuat permintaan AJAX, pengaturan permintaan tersebut dapat dilihat di konsol browser. Beberapa pengaturan mungkin berisi informasi sensitif seperti kunci atau token API. Cara yang disarankan untuk mencegah perilaku ini adalah dengan menggunakan OAuth Authentication
. Pilihan lainnya bisa menggunakan Secure Settings
. Pilih opsi apa pun yang paling cocok untuk Anda.
Anda dapat menggunakan OAuth2 untuk mengautentikasi semua permintaan API Anda ke layanan eksternal. OAuth memberikan cara yang aman bagi aplikasi Anda untuk mengakses data akun Anda tanpa memerlukan informasi sensitif seperti nama pengguna dan sandi untuk dikirimkan bersama permintaan tersebut. Untuk menggunakan autentikasi OAuth, Anda perlu mendaftarkan aplikasi Anda ke layanan pihak ketiga guna menghasilkan kredensial OAuth untuk aplikasi Anda. Anda juga perlu menambahkan beberapa fungsi ke aplikasi Anda untuk mengimplementasikan alur otorisasi OAuth.
Saat mendaftarkan aplikasi, Anda akan disajikan layar yang menunjukkan pengaturan untuk aplikasi baru Anda termasuk nama aplikasi, deskripsi, dan informasi aplikasi lainnya yang harus Anda isi. Selain itu, Anda juga akan menemukan pengaturan Auth untuk aplikasi Anda seperti ID klien, rahasia klien, URL pengalihan, serta cakupan yang digunakan oleh aplikasi Anda. Anda memerlukan item ini saat memulai koneksi OAuth antara aplikasi Anda dan layanan pihak ketiga.
Client ID
- ID ini unik untuk aplikasi Anda dan digunakan untuk memulai OAuth.Client secret
- Digunakan untuk membuat dan menyegarkan autentikasi OAuth.Redirect URL
- Pengguna akan dialihkan ke lokasi ini setelah memberikan akses ke aplikasi Anda. Gunakan salah satu url berikut:Scope
- Tindakan keamanan opsional. Cakupan menentukan data apa yang boleh diakses oleh aplikasi Anda.OAuth URL
- Pengguna memerlukan URL ini untuk menghubungkan aplikasi Anda. URL sedang dibuat berdasarkan kredensial klien aplikasi Anda, URL pengalihan, dan konfigurasi cakupan. Gunakan Client ID
dan Client secret
dalam aplikasi Anda seperti yang dijelaskan di bagian berikut ini.
Setelah Anda mendaftarkan aplikasi, Anda harus menentukan pengaturan OAuth di file manifest.json
. Perbarui client_id
dan client_secret
dengan milik Anda.
"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 "
}
Anda juga perlu menambahkan parameter tipe "oauth" ke daftar parameter:
"parameters" : [
{
"name" : " access_token " ,
"type" : " oauth "
}
]
Untuk informasi lebih lanjut kunjungi dokumen
Dalam kode aplikasi Anda, gunakan placeholder {{setting.access_token}}
dan properti secure: true
untuk membuat permintaan 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 ( ... ) ;
Ini adalah API khusus JSON. Anda harus menyediakan header Content-Type: application/json
pada permintaan PUT dan POST. Anda harus menyetel header Accept: application/json
pada semua permintaan.
var settings = {
url : 'https://www.example.com/api/user' ,
dataType : 'json' ,
contentType : 'application/json' ,
...
} ;
Pengaturan aman adalah cara lain untuk membuat pengaturan tidak dapat diakses oleh agen saat membuat permintaan AJAX. Nilai pengaturan hanya dimasukkan di sisi server permintaan keluar pada lapisan proksi. Lihat Menggunakan pengaturan aman untuk mengaturnya.
Meskipun Anda dapat menggunakan CSS khusus atau kerangka front-end apa pun untuk tampilan dan nuansa aplikasi Anda, Zendesk merekomendasikan penggunaan Zendesk Garden. Zendesk Garden dirancang untuk menjadi garis dasar umum gaya dan komponen di antara semua produk Zendesk. Untuk membuat aplikasi Anda cocok dengan tampilan dan nuansa Zendesk, Zendesk Garden digunakan di aplikasi sebagai default.
Contoh:
. YourElement {
color : var ( --zd-color-green-600 );
padding : var ( --zd-spacing-sm );
}
Untuk informasi selengkapnya tentang kelas CSS dan komponen React di Zendesk Garden, lihat garden.zendesk.com.
Klien ZAF memungkinkan aplikasi Anda di iframe berkomunikasi dengan produk host Zendesk. Anda dapat menggunakan klien di aplikasi Anda untuk mendengarkan peristiwa, menjalankan tindakan, dan mengakses properti di setiap lokasi. Lihat panduan API Klien ZAF.
Contoh:
const client = ZAFClient . init ( )
client . get ( 'contact.email' ) . then ( function ( data ) {
console . log ( data ) // { "contact.email": "[email protected]" }
} )
Paket @zendesk/sell-zaf-app-toolbox memberikan banyak metode, kait, dan komponen berguna yang membantu Anda membangun aplikasi React yang terintegrasi dengan Zendesk Sell dengan lebih cepat dan mudah. Mereka menggunakan Klien Kerangka Aplikasi Zendesk. Untuk mengetahui lebih lanjut kunjungi repositori.
Gunakan antarmuka baris perintah Anda, navigasikan ke folder yang berisi aplikasi yang ingin Anda uji.
Instal dependensi jika perlu:
npm install
Mulai aplikasi Anda dengan perintah berikut:
npm start
Buka jendela baru di terminal Anda dan mulai server:
npm run server
Di browser, navigasikan ke halaman produk tempat Anda menentukan aplikasi untuk muncul (misalnya kesepakatan/prospek/kartu kontak) dan tambahkan ?zcli_apps=true
ke URL. Contoh:
https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true
Di bilah Alamat browser Anda, klik ikon perisai di sebelah kanan (Chrome) atau ikon kunci di sebelah kiri (Firefox) dan setuju untuk memuat skrip yang tidak aman (Chrome) atau untuk menonaktifkan perlindungan (Firefox).
Catatan: Safari tidak memiliki opsi untuk menonaktifkan perlindungan.
Untuk lint dan memperbaiki beberapa kesalahan secara otomatis, jalankan:
npm run lint
Untuk memformat kode Anda:
npm run prettier
Bangun paket dengan sumber yang diperkecil:
npm run build
Perintah tersebut membuat file .zip baru di dist/tmp
. Sekarang aplikasi Anda siap dipasang sebagai aplikasi pribadi di Zendesk Sell Anda!
Integrations
lalu pilih tab Apps
.Upload private app
.dist/tmp
di proyek aplikasi lokal Anda.Jika aplikasi Anda menggunakan OAuth atau setelan aman, Anda dapat terus mengujinya secara lokal setelah menginstalnya dari jarak jauh.
zcli.apps.config.json
plan
dan paramters
). {
"plan" : " silver " ,
"app_id" : YOUR_APP_ID,
"parameters" : {}
}
Untuk menemukan id instalasi aplikasi, masuk ke instance Zendesk Sell Anda sebagai admin dan buka halaman berikut di browser yang sama, ganti your_subdomain
dengan milik Anda sendiri:
https://your_subdomain.zendesk.com/api/sell/apps/installations.json (dalam produksi)
Temukan aplikasi yang Anda instal dan catat nilai id
-nya, bukan nilai app_id
-nya.