sell zaf app scaffold

Zendesk App Framework(ZAF) React Skeleton สำหรับการขายแอป

แพ็คเกจนี้ช่วยให้คุณสามารถบูตแอปพลิเคชันที่ใช้ React ซึ่งผสานรวมกับ Zendesk App Framework (ZAF) และช่วยให้คุณสามารถเริ่มต้นพัฒนาแอปสำหรับ Zendesk Sell ได้อย่างรวดเร็ว

หมายเหตุ: เอกสารนี้อ้างอิงจากคู่มือ Zendesk Developer พวกเขามีเฉพาะข้อมูลที่เลือกสรรและหวังว่าจะเป็นข้อมูลที่จำเป็นที่สุดในแง่ของการสร้างแอปที่รวมเข้ากับ Zendesk Sell หากคุณประสบปัญหาหรือมีข้อมูลไม่เพียงพอ โปรดไปที่เอกสารประกอบจริง

ข้อกำหนดเกี่ยวกับไฟล์

โครงสร้างโฟลเดอร์และไฟล์ต่อไปนี้จะต้องรวมอยู่ในแอปเพื่อติดตั้งแอปในผลิตภัณฑ์ Zendesk ได้สำเร็จ:

 assets/
  logo.png
  logo-small.png
translations/
  en.json
manifest.json

ต่อไปนี้เป็นคำอธิบายโดยย่อของไฟล์ที่จำเป็น:

• manifest.json - อธิบายและกำหนดค่าแอป ดูการอ้างอิงรายการ
• Translations/en.json - ไฟล์แปลภาษาอังกฤษมาตรฐาน ดูการทำให้เป็นสากล
• Assets/logo-small.png (128x128px) - ไอคอนขนาดเล็กที่แสดงอยู่ที่ส่วนหัวของแอป ดูไอคอนแอปสำหรับข้อมูลจำเพาะของรูปภาพ
• Assets/logo.png (320x320px) - ไอคอนขนาดใหญ่ที่แสดงในหน้าผู้ดูแลระบบ Zendesk สำหรับการจัดการแอป ดูไอคอนแอปสำหรับข้อมูลจำเพาะของรูปภาพ

ตัวอย่างรายการแอป 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 "
  }
}

การตั้งค่าตำแหน่งของแอป

คุณต้องประกาศว่าต้องการให้แอปของคุณปรากฏที่ใดในอินเทอร์เฟซผลิตภัณฑ์แต่ละรายการด้วยคุณสมบัติ location ใน manifest.json ตำแหน่งคือตำแหน่งที่ iframe สามารถปรากฏในผลิตภัณฑ์ได้ คุณสามารถระบุสถานที่อย่างน้อยหนึ่งแห่งในผลิตภัณฑ์ Zendesk หนึ่งรายการขึ้นไป ตามค่าเริ่มต้น แอปของคุณจะพร้อมใช้งานใน Zendesk Sell บนออบเจ็กต์การ์ดทั้งหมด (Lead, Contact, Deal) ในแผงทางด้านขวา

 "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 "
    }
  }
}

สำหรับสถานที่ตั้งที่มีจำหน่าย โปรดดูที่การขาย Apps API หากต้องการข้อมูลเพิ่มเติมเกี่ยวกับการตั้งค่าตำแหน่งแอป โปรดไปที่ส่วนการตั้งค่าตำแหน่งแอปในคู่มือนักพัฒนา

ความปลอดภัยและการรับรองความถูกต้อง

เมื่อแอปส่งคำขอ AJAX คุณจะดูการตั้งค่าสำหรับคำขอได้ในคอนโซลของเบราว์เซอร์ การตั้งค่าบางอย่างอาจมีข้อมูลที่ละเอียดอ่อน เช่น คีย์ API หรือโทเค็น วิธีที่แนะนำในการป้องกันพฤติกรรมนี้คือการใช้ OAuth Authentication ตัวเลือกอื่นสามารถใช้ Secure Settings เลือกตัวเลือกใดก็ได้ที่เหมาะกับคุณที่สุด

การรับรองความถูกต้อง OAuth

คุณสามารถใช้ OAuth2 เพื่อตรวจสอบสิทธิ์คำขอ API ทั้งหมดของคุณไปยังบริการภายนอก OAuth มอบวิธีที่ปลอดภัยสำหรับแอปพลิเคชันของคุณในการเข้าถึงข้อมูลบัญชีของคุณ โดยไม่ต้องส่งข้อมูลที่ละเอียดอ่อน เช่น ชื่อผู้ใช้และรหัสผ่านไปพร้อมกับคำขอ หากต้องการใช้การตรวจสอบสิทธิ์ OAuth คุณต้องลงทะเบียนแอปพลิเคชันของคุณกับบริการของบุคคลที่สามเพื่อสร้างข้อมูลรับรอง OAuth สำหรับแอปของคุณ คุณต้องเพิ่มฟังก์ชันการทำงานบางอย่างให้กับแอปพลิเคชันของคุณเพื่อใช้ขั้นตอนการให้สิทธิ์ OAuth

การลงทะเบียนแอปกับบริการของบุคคลที่สาม

เมื่อลงทะเบียนแอป คุณจะเห็นหน้าจอแสดงการตั้งค่าสำหรับแอปใหม่ของคุณ รวมถึงชื่อแอป คำอธิบาย และข้อมูลแอปอื่นๆ ที่คุณควรกรอก นอกจากนี้ คุณยังจะพบการตั้งค่าการตรวจสอบสิทธิ์สำหรับ แอปของคุณ เช่น รหัสไคลเอ็นต์ รหัสลับไคลเอ็นต์ URL การเปลี่ยนเส้นทาง รวมถึงขอบเขตที่แอปของคุณใช้ คุณจะต้องมีรายการเหล่านี้เมื่อเริ่มต้นการเชื่อมต่อ OAuth ระหว่างแอปของคุณและบริการของบุคคลที่สาม

• Client ID - รหัสนี้เป็นรหัสเฉพาะสำหรับแอปของคุณ และใช้สำหรับเริ่มต้น OAuth
• Client secret - ใช้เพื่อสร้างและรีเฟรชการตรวจสอบสิทธิ์ OAuth
• Redirect URL - ผู้ใช้จะถูกเปลี่ยนเส้นทางไปยังตำแหน่งนี้หลังจากให้สิทธิ์การเข้าถึงแอปของคุณ ใช้หนึ่งใน URL ต่อไปนี้:
  • https://zis.zendesk.com/api/services/zis/connections/oauth/callback (ในการใช้งานจริง)
  • https://zis.zendesk-staging.com/api/services/zis/connections/oauth/callback (ในการจัดเตรียม)
• Scope - มาตรการรักษาความปลอดภัยเพิ่มเติม ขอบเขตจะกำหนดว่าแอปของคุณมีสิทธิ์เข้าถึงข้อมูลใดบ้าง
• OAuth URL - ผู้ใช้จะต้องมี URL นี้เพื่อเชื่อมต่อแอปของคุณ URL กำลังถูกสร้างขึ้นตามข้อมูลรับรองไคลเอ็นต์ของแอป URL การเปลี่ยนเส้นทาง และการกำหนดค่าขอบเขต

ใช้ Client ID และ Client secret ในแอปพลิเคชันของคุณตามที่อธิบายไว้ในส่วนต่อไปนี้

การใช้ OAuth ในแอป

เมื่อคุณลงทะเบียนแอปแล้ว คุณจะต้องกำหนดการตั้งค่า 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 "
  }
]

สำหรับข้อมูลเพิ่มเติมโปรดไปที่เอกสาร

โทเค็นการเข้าถึง 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 ค่าการตั้งค่าจะถูกแทรกเฉพาะในฝั่งเซิร์ฟเวอร์คำขอขาออกที่ชั้นพร็อกซีเท่านั้น ดูการใช้การตั้งค่าความปลอดภัยเพื่อตั้งค่า

การใช้ Zendesk Garden

แม้ว่าคุณสามารถใช้ 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

ไคลเอนต์ 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-กล่องเครื่องมือ

แพ็คเกจ @zendesk/sell-zaf-app-toolbox มอบวิธีการ ฮุค และส่วนประกอบที่มีประโยชน์มากมาย ซึ่งจะช่วยให้คุณสร้างแอป React ที่ผสานรวมเข้ากับ Zendesk Sell ได้เร็วยิ่งขึ้นและใช้ความพยายามน้อยลง พวกเขาใช้ App Framework Client ของ Zendesk ภายใต้ประทุน หากต้องการข้อมูลเพิ่มเติม โปรดไปที่พื้นที่เก็บข้อมูล

การทดสอบแอปในเครื่อง

1. ใช้อินเทอร์เฟซบรรทัดคำสั่งของคุณไปยังโฟลเดอร์ที่มีแอปที่คุณต้องการทดสอบ

2. ติดตั้งการพึ่งพาหากจำเป็น:

   npm install

3. เริ่มแอปของคุณด้วยคำสั่งต่อไปนี้:

   npm start

4. เปิดหน้าต่างใหม่ในเทอร์มินัลของคุณและเริ่มเซิร์ฟเวอร์:

    npm run server
   

5. ในเบราว์เซอร์ ให้นำทางไปยังหน้าผลิตภัณฑ์ที่คุณระบุแอปที่จะแสดง (เช่น ดีล/ลีด/การ์ดผู้ติดต่อ) และต่อท้าย ?zcli_apps=true ต่อท้าย URL ตัวอย่าง:

   https://app.futuresimple.com/crm/contacts/1234?zcli_apps=true

6. ในแถบที่อยู่ของเบราว์เซอร์ของคุณ คลิกไอคอนรูปโล่ทางด้านขวา (Chrome) หรือไอคอนแม่กุญแจทางด้านซ้าย (Firefox) และตกลงที่จะโหลดสคริปต์ที่ไม่ปลอดภัย (Chrome) หรือปิดการใช้งานการป้องกัน (Firefox)

   หมายเหตุ: Safari ไม่มีตัวเลือกในการปิดการป้องกัน

วิ่งลินเตอร์

เพื่อขุยและแก้ไขข้อผิดพลาดบางอย่างโดยอัตโนมัติให้รัน:

npm run lint

วิ่งสวยขึ้น.

เพื่อจัดรูปแบบโค้ดของคุณ:

npm run prettier

ซิปอาคาร

สร้างแพ็คเกจด้วยซอร์สย่อส่วน:

npm run build

คำสั่งสร้างไฟล์ .zip ใหม่ใน dist/tmp ตอนนี้แอปของคุณพร้อมที่จะติดตั้งเป็นแอปส่วนตัวใน Zendesk Sell ของคุณแล้ว!

การติดตั้งแอปส่วนตัวใน Zendesk Sell

1. ไปที่การตั้งค่า Zendesk Sell ของคุณ
2. ค้นหาส่วน Integrations จากนั้นเลือกแท็บ Apps
3. คลิกปุ่ม Upload private app
4. ตั้งชื่อแอปของคุณและอัปโหลดไฟล์ .zip ล่าสุดจาก dist/tmp ในโปรเจ็กต์แอปในเครื่องของคุณ
5. ติดตั้งแอป

การทดสอบแอปด้วย OAuth หรือการตั้งค่าความปลอดภัยในเครื่อง

หากแอปของคุณใช้ OAuth หรือการตั้งค่าความปลอดภัย คุณสามารถทดสอบแอปในเครื่องต่อไปได้หลังจากติดตั้งจากระยะไกล

1. ติดตั้งแอปเป็นแอปส่วนตัวใน Zendesk Sell ดูการติดตั้งแอปส่วนตัวใน Zendesk Sell
2. นำทางไปยังโฟลเดอร์รูทของแอปและสร้างไฟล์ชื่อ zcli.apps.config.json
3. วางเนื้อหาด้านล่าง (หมายเหตุ: คุณสามารถแก้ไข 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 (ในการใช้งานจริง)

ค้นหาแอปที่ติดตั้งแล้วจดค่า id ไม่ใช่ค่า app_id

3. ทดสอบแอปตามปกติกับเซิร์ฟเวอร์ภายในเครื่อง ดูการทดสอบแอปในเครื่อง