वेब विजेट

तकनीकी नाम जैसे window.SingChat विजेट और API का हिस्सा हैं। इन्हें अपने कोड में बिल्कुल वैसे ही रखें।

वेब विजेट एक ही स्क्रिप्ट widget.js है, जो cs.askais.com से दी जाती है। यह आपके पेजों पर चैट खोलने का बटन जोड़ती है और चैट विंडो को एक Shadow DOM के अंदर बनाती है, ताकि आपकी साइट की स्टाइल और विजेट की स्टाइल अलग-अलग रहें।

इसे अपनी साइट पर जोड़ें

इसे हर उस पेज पर </body> से पहले पेस्ट करें जहाँ चैट दिखनी चाहिए। आपकी ऐप ID सेटिंग्स → इनबॉक्स में है।

<script src="https://cs.askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://cs.askais.com"
  async></script>

आपकी अपनी साइट पर data-base-url ज़रूरी है: इसके बिना विजेट अपना सर्वर cs.askais.com के बजाय आपके डोमेन पर ढूँढता है।

⚠️ widget.js को cs.askais.com से लोड करें

widget.js को डाउनलोड न करें और न ही उसे अपने कोड में बंडल करें। cs.askais.com से लोड होने पर यह हमेशा मौजूदा वर्शन चलाता है; उसकी कॉपी पुरानी हालत में अटकी रहती है और हर फ़िक्स और हर नई सुविधा से चूक जाती है।

स्क्रिप्ट एट्रिब्यूट

सब कुछ स्क्रिप्ट टैग पर data- एट्रिब्यूट से सेट होता है:

• data-app-id — ज़रूरी। आपके इनबॉक्स की ऐप ID।
• data-base-url — आपकी साइट पर ज़रूरी। हमेशा https://cs.askais.com।
• data-locale — वैकल्पिक। विजेट की भाषा तय करता है, जैसे ja या zh-Hant। इसे छोड़ दें तो विजेट विज़िटर के डिवाइस की भाषा अपनाता है, फिर आपके पेज की lang।
• data-external-id — साइन-इन किए हुए यूज़र के लिए आपकी अपनी ID।
• data-email — यूज़र का ईमेल, जो आपकी टीम को दिखता है।
• data-name — यूज़र का नाम, जो आपकी टीम को दिखता है।
• data-avatar-url — यूज़र की प्रोफ़ाइल फ़ोटो का लिंक।
• data-hmac — पहचान का हस्ताक्षर, नीचे देखें।
• data-attrs — JSON के रूप में अतिरिक्त जानकारी, जैसे {"plan":"Pro"}, जो विज़िटर की प्रोफ़ाइल में आपकी टीम को दिखती है। अमान्य JSON को अनदेखा कर दिया जाता है।

data-embed, data-platform, data-app-version और data-device-model को ऐप में चैट वाला पेज सेट करता है। ऐप में चैट (WebView) देखें।

साइन-इन किए हुए विज़िटर

साइन-इन किए हुए यूज़र के लिए उसकी जानकारी स्क्रिप्ट टैग में जोड़ें। आपकी टीम देख पाती है कि वह किससे बात कर रही है, और चैट दूसरे डिवाइस पर भी यूज़र के साथ रहती है:

<script src="https://cs.askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://cs.askais.com"
  data-external-id="user_123"
  data-email="[email protected]"
  data-name="Ada Lovelace"
  data-attrs='{"plan":"Pro"}'
  data-hmac="SIGNATURE_FROM_YOUR_SERVER"
  async></script>

data-external-id के बिना विजेट हर ब्राउज़र को उसकी अपनी गुमनाम ID देता है, जो ब्राउज़र के local storage में रखी जाती है, इसलिए उस ब्राउज़र में पेज दोबारा लोड करने पर भी चैट हिस्ट्री बनी रहती है। अगर इनबॉक्स में प्री-चैट फ़ॉर्म है, तो गुमनाम विज़िटर चैट शुरू होने से पहले उसे भरते हैं।

सत्यापित पहचान (HMAC)

• hmac असल में externalId का HMAC-SHA256 है, जो इनबॉक्स की सीक्रेट की से बनाया जाता है और छोटे अक्षरों वाले hex में लिखा जाता है।
• इसे अपने सर्वर पर कैलकुलेट करें। सीक्रेट की कभी किसी पेज या ऐप में नहीं जाती।
• सीक्रेट की इनबॉक्स बनाते समय एक बार दिखती है, और फिर तब जब आप उसे सेटिंग्स → इनबॉक्स में रोटेट करते हैं (उस इनबॉक्स का ⋮ मेनू → सीक्रेट की रोटेट करें)। पूरी की इस्तेमाल करें, sk_ प्रीफ़िक्स सहित। रोटेट करने से सभी पुराने हस्ताक्षर अमान्य हो जाते हैं।
• data-external-id को हमेशा data-hmac के साथ भेजें, और ठीक उसी मान पर हस्ताक्षर करें। विजेट हमेशा external ID भेजता है (आप न दें तो ख़ुद गुमनाम ID बना लेता है), इसलिए सिर्फ़ ईमेल पर बना हस्ताक्षर कभी किसी को सत्यापित नहीं करता।
• ग़लत या ग़ायब हस्ताक्षर चैट को कभी नहीं रोकता: विज़िटर आपसे बात कर सकता है, लेकिन उसे असत्यापित माना जाता है। असत्यापित जानकारी वैसे ही मान ली जाती है जैसे पेज देता है, इसलिए जो भी पेज बदल सकता है वह किसी और होने का दावा कर सकता है, जब तक आप पहचान सत्यापन अनिवार्य करें चालू न करें, जिससे असत्यापित विज़िटर गुमनाम माने जाते हैं और पुरानी बातचीत नहीं देखते।

Node.js के लिए उदाहरण:

import { createHmac } from "node:crypto";

// Runs on your server. INBOX_SECRET_KEY never leaves it.
const hmac = createHmac("sha256", INBOX_SECRET_KEY)
  .update(user.id) // the exact value you pass as data-external-id
  .digest("hex");

JavaScript से विजेट शुरू करना

विजेट को खुद शुरू करने के लिए, जैसे जब आपके पेज को पता चल जाए कि यूज़र कौन है, स्क्रिप्ट को data-app-id के बिना लोड करें और उसके लोड होने के बाद window.SingChat.start() कॉल करें:

<script src="https://cs.askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://cs.askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "[email protected]",
    name: "Ada Lovelace",
    hmac: "SIGNATURE_FROM_YOUR_SERVER",
  });
</script>

start() ही वह अकेला मेथड है जो स्क्रिप्ट देती है। विजेट को खोलने, बंद करने या उसके इवेंट सुनने के लिए कोई मेथड नहीं है; विज़िटर उसे चैट बटन से खोलते हैं।

रूप और व्यवहार

• सेटिंग्स → इनबॉक्स, फिर किसी इनबॉक्स को एक्सपैंड करें: प्राथमिक रंग और टेक्स्ट रंग, स्थिति (नीचे दाएँ या नीचे बाएँ), बबल आकार, हल्का या गहरा बैकग्राउंड, विंडो शीर्षक और उपशीर्षक, लाइव पूर्वावलोकन के साथ।
• प्री-चैट फ़ॉर्म (उसी जगह): चैट शुरू होने से पहले गुमनाम विज़िटर से उनका ईमेल, नाम, फ़ोन या कंपनी पूछें।
• अनुमत ऑरिजिन (उसी जगह): वे वेबसाइटें जो इस इनबॉक्स का विजेट लोड कर सकती हैं। सूची खाली हो तो कोई भी साइट उसे लोड कर सकती है।
• विजेट ब्रांडिंग (उसी जगह): चैट के नीचे “Powered by” वाली लाइन। आप इसे छिपा सकते हैं या वहाँ अपना नाम दिखा सकते हैं या नहीं, यह आपके प्लान पर निर्भर है।
• AI का स्वागत मैसेज AI एजेंट में सेट होता है, क्लिक किए जा सकने वाले FAQ बबल सेटिंग्स → अक्सर पूछे जाने वाले प्रश्न में, और लेख Help Center में।

सुरक्षा

• ऐप ID सार्वजनिक है और आपके HTML में सुरक्षित है।
• इनबॉक्स की सीक्रेट की सिर्फ़ आपके सर्वर पर होनी चाहिए।
• जब भी पेज को पता हो कि यूज़र कौन है, सत्यापित पहचान (HMAC) इस्तेमाल करें।
• अनुमत ऑरिजिन को अपने डोमेन तक सीमित रखें, ताकि विजेट दूसरी साइटों पर लोड न हो सके।