Official API

Thiết lập kết nối

Truyền thông tin người dùng vào form

Webhook

Dữ liệu khảo sát

Giới thiệu

Official API Cung cấp cách thức để ứng dụng của bạn có thể truyền thông tin người dùng qua form và nhận về kết quả sau khi người dùng hoàn thành form. Bằng cách này ứng dụng của bạn sẽ biết người dùng đó là ai và đã trả lời form với nội dung là gì.

Để sử dụng Official API bạn cần đăng ký Secret Key và tuân thủ các điều khoản do {{host}} phát hành.

Secret Key

Secret Key là mã truy cập do Admin cấp cho tài khoản người dùng để gọi các API nhằm mục đích hỗ trợ quản lý khảo sát, lưu trữ kết quả khảo sát, tự động quy trình chăm sóc khách hàng khi khách phản hồi góp ý qua khảo sát.

Secret Key
Lưu ý: Hãy bảo mật Secret Key của bạn
{{hideSecretKey()}}
{{SDK.secretKey}}
Secret Key

Bạn cần đăng nhập để tạo Secret Key

Secret Key

Tài khoản của bạn chưa tạo Secret Key!

Tạo Secret Key

Survey ID

Đây là công cụ hỗ trợ lấy survey id từ link khảo sát. Bạn hãy sao chép được link của khảo sát và dán vào ô bên dưới, sau đó hãy nhấn nút Lấy Survey ID.

Survey ID

Bạn cần đăng nhập để thực hiện hành động này

Đường link khảo sát
Lấy Survey ID
Survey ID
{{surveyId}}
Tiêu đề khảo sát
{{surveyTitle}}
Trạng thái
{{status}}
Ngày tạo
{{convertUTCToDDMMYYYYHHMM(dateCreated)}}

Key Hash

Key Hash là kết quả của việc hash Secret Key

Key Hash của bạn là:
{{hideKeyHash()}}
{{SDK.keyHash}}
Key Hash

Tài khoản của bạn chưa đăng ký Secret Key, vui lòng đăng ký tại đây

Hàm Hash
Dưới đây là hàm Hash trên NodeJS để tạo ra Key Hash từ Secret Key của bạn
function hashSecretKey(secretKey) {
let keyMd5 = crypto.createHash('md5').update(secret).digest();
let keyHash = crypto.createHash('md5').update(keyMd5).digest('hex');
return keyHash;
}

Giới thiệu

Làm sao để biết người dùng/khách hàng vừa mới hoàn thành khảo sát là ai? Để trả lời câu hỏi này, {{host}} hỗ trợ bạn truyền dữ liệu định danh người dùng/khách hàng của bạn vào form khảo sát.

Sau khi người dùng/khách hàng đó hoàn thành khảo sát, hệ thống sẽ ghi nhận dữ liệu định danh mà bạn đã truyền qua form. Bạn sẽ nhận được các thông tin định danh mà bạn đã truyền qua form trong báo cáo.

Cài đặt

Giới thiệu

{{host}} cho phép bạn truyền dữ liệu định danh khách hàng qua các tham số trên URL của form khảo sát để biết được người vừa tham gia khảo sát là ai hoặc đến từ cửa hàng nào.

Ưu điểm của cách thức không mã hóa này là bạn có thể linh động tùy chỉnh và dễ dàng thiết lập.

Nhược điểm của cách thức này là người dùng/khách hàng dễ dàng can thiệp vào URL để thay đổi tham số. {{host}} khuyến cáo không nên sử dụng cách thức này để định danh người dùng trên các khảo sát có bốc thăm trúng thưởng hoặc chương trình tặng quà.

Thông số kỹ thuật:
Method:
GET
URL:
https://{{host}}/survey/surveyURL?param1=value1&param2=value2
Ví dụ
https://{{host}}/survey/customer-survey-52f5f6f?userId=98830212&store=dongkhoi
Mô tả tham số
Tham sốMô tả

surveyURL

String

Đường link của khảo sát mà người dùng đang tương tác

param1

String

Là tên của tham số mà bạn muốn truyền vào form khảo sát

Ví dụ userId

value1

String

Là giá trị của tham số param1 mà bạn muốn truyền vào form khảo sát

Ví dụ 98830212 là mã định danh user trên hệ thống của bạn

param2

String

Là tên của tham số mà bạn muốn truyền vào form khảo sát

Ví dụ store

value2

String

Là giá trị của tham số param2 mà bạn muốn truyền vào form khảo sát

Ví dụ dongkhoi là mã cửa hàng trên hệ thống của bạn

Bạn có thể truyền nhiều tham số

Giới thiệu về Webhook

{{host}} sẽ gửi các request https (method POST) đến webhook url của đơn vị thứ 3 khi có người dùng hoàn thành khảo sát. Các sự kiện webhook được gửi dưới dạng các yêu cầu POST đến webhook đã đăng ký trong phần Cài đặt Webhook.

Chú ý: Để đạt hiểu suất cao nhất. Webhook Url không nên dùng host:port, thay vào đó hãy dùng domain và phải được cấu hình https.

Yêu cầu hiệu suất cho webhook:

  1. Phản hồi tất cả sự kiện webhook với http status code = 200 OK.
  2. Phản hồi tất cả sự kiện webhook tối đa 2 giây.

    3. Cài đặt Webhook

    Thiết lập Webhook
    Đăng nhập để thực hiện thao tác này
    Tài khoản của bạn chưa đăng ký Secret Key, vui lòng đăng ký tại đây
    Khai báo Webhook
    {{ webhook.url }}
    Bạn chưa khai báo Webhook URL
    Thay đổiThêm mới
    Lưu
    Huỷ
    Kích hoạt Webhook

    Bạn cần nâng cấp lên tài khoản Doanh nghiệp để thực hiện hành động nàyTài khoản Doanh nghiệp đã hết hạn để thực hiện hành động này

    Encrypt Data
    Chỉ gọi Webhook khi có Payload được truyền vào link khảo sát
    Http Basic Authentication
    User
    {{ webhook.authentication.user }}
    Bạn chưa khai báo User
    Thay đổiThêm mới
    Lưu
    Huỷ
    Password
    ***
    Bạn chưa khai báo Password
    Thay đổiThêm mới
    Lưu
    Huỷ
    Mô tả Webhook
    {{host}} sẽ gọi Webhook URL mà bạn đã cung cấp để trả kết quả khảo sát. Nội dung mà {{host}} gửi có cấu trúc như sau:
    Method:
    POST
    Content Type:
    application/json
    URL:
    {{ webhook.url }}
    Dữ liệu trước khi mã hóa:
    Dữ liệu bạn sẽ nhận được:
    {
    surveyId: "5fd5acb40f8651623349727f",
    customPayload: "{ fieldA : 100, fieldB: 200, fieldC: 300}",
    customResponseText: "This is custom response text which is generated from client side by consuming template + userInput in userAnswerSurvey",
    answerSurveyData: [{
    questionId: 1,
    question: "This is the first question title",
    answers: ["This is the first chosen answer", "This is the second one"],
    }]
    }
    Mô tả thuộc tính
    Thuộc tínhMô tả

    surveyId

    String

    		Id của khảo sát mà người dùng đang tương tác

    customPayload

    String

    Là toàn bộ dữ liệu được gửi đến form thông qua các tham số được gắn trên url của khảo sát.

    Trường này là object đã được stringify.

    customResponseText

    String

    Là phần nội dung bình luận đã được xử lý dựa trên các bình chọn của user.

    Trường này chỉ có khi khảo sát có bật tính năng Customized Message trong khảo sát

    answerSurveyData

    JSONObject

    Là dữ liệu kết quả khảo sát.

    Trường này chỉ có khi khảo sát có bật tính năng Asnwer Survey Data trong khảo sát

    Dữ liệu đã được mã hóa mà bạn sẽ nhận được
    Nội dung dữ liệu đã được mã hóa
    {
    keyHash: "f6f67505d050014a62cee9c23f88d801",
    encryptedPayload: "iRncXijEsc%2BwvnzwL0V64Yg0WDyA5tg2HOC71f08yKVpnNzitJjvwWhQ%2B1cYQASxGIDoIU35ISC%2FERsQC%2BIypmZHdw9xC07yKcveezVByDaF5tkp9v%2Bk4HvGSpkCnYBQ9w2fCh5vssRi0Ad17onVT90wXDmmIzb0z%2FRndNAH9cvuR1Z2DUboB8xOvWEhCTy916uec7dRtGvSTrwfgxbOxayase8TuUln6lN%2FvhBb4Cyl163b8%2F4lSIKgBzDb1fzcdBgL1Ju8feul6CCisn6u1qqITDbIIQVSm6%2BSxn2TXnJexol7t5ZAs1uWAzZHEzrVLExJcHm4vvY3cSXpSc%2BWNlirh755w1S6F4W4U4YTMbZV9abyr8aceL1pyAk8cn1mzK5QF24U%2B5qbfxh1d5uWEnM5Bzx3aGI1mFqw8gB9XfLKByfeuRwtnBTFw8d6HaNd",
    }
    Thuộc tínhMô tả

    keyHash

    String

    		Là kết quả Secret Key qua hàm hash MD5.

    encryptedPayload

    String

    		Là dữ liệu đã được mã hóa do {{host}} gửi đến Webhook URL.
    Hàm giải mã dữ liệu
    function decodeBase64AndDecryptData(encryptedPayload, secretKey) {
    let keyMd5 = crypto.createHash('md5').update(secretKey).digest();
    let decoded = Buffer.from(decodeURIComponent(encryptedPayload), 'base64');
    let iv = Buffer.alloc(16);
    let encrypted = Buffer.alloc(decoded.length - iv.length);
    decoded.copy(iv, 0, 0);
    decoded.copy(encrypted, 0, iv.length);
    let dec = crypto.createDecipheriv('aes-128-cbc', keyMd5, iv);
    let decrypted = Buffer.concat([dec.update(encrypted), dec.final()]);
    let decryptedMsg = decrypted.toString();
    return decryptedMsg;
    }
    Thuộc tínhMô tả

    encryptedPayload

    String

    		Là dữ liệu mã hóa được gửi đến Webhook URL.

    secretKey

    String

    Là Secret Key được cung cấp cho developer ở mục Secret Key của hướng dẫn này.

    Vui lòng đăng nhập để lấy Secret Key.

    Test Webhook URL
    Gửi test data tới Webhook URL
    {{ webhook.url }}
    Vui lòng khai báo Webhook URL ở phần Thiết lập Webhook
    Gửi
    Gửi

    Lấy dữ liệu khảo sát

    Bạn có thể tải dữ liệu khảo sát thông qua API này

    Thông số kỹ thuật:
    Method:
    GET
    URL:
    https://{{host}}/api/userAnswers?surveyId=xxx &keyhash=yyy &page=zzz
    Mô tả tham số
    Tham sốMô tảBắt buộc

    surveyId

    String

    		Id của khảo sát mà người dùng đang tương tác. Lấy SurveyId tại đây.YES

    keyhash

    String

    Là kết quả Secret Key qua hàm hash MD5. Lấy Key Hash tại đây.

    		YES

    page

    String

    Cần tải dữ liệu của trang thứ bao nhiêu.

    Giá trị mặc định là 1 khi không khai báo.

    		NO
    Kết quả trả về
    Định dạng:
    JSON
    Thành công
    Response = {
    success: {type: Boolean},
    data: [{
    questions : [{
    questionId: {type: number},
    question: {type: String},
    answers: [{type: String}],
    }],
    dateCreated: {type: Date},
    extraInfo: [{
    key : {type: String},
    value : {type: String}
    }],
    }],
    currentPage: {type: Number}, // Current Page index. Starting from 1.
    pageSize: {type: Number}, // page size: the number of items in current page
    totalPage: {type: Number}, // Total number of Page
    }
    Thất bại
    Response = {
    success: {type: Boolean},
    message: {type: String},
    }

    Lấy báo cáo thống kê của khảo sát

    Bạn có thể tải dữ liệu báo cáo thống kê khảo sát thông qua API này

    Thông số kỹ thuật:
    Method:
    GET
    URL:
    https://{{host}}/api/reportData?surveyId=xxx &keyhash=yyy
    Mô tả tham số
    Tham sốMô tảBắt buộc

    surveyId

    String

    		Id của khảo sát mà người dùng đang tương tác. Lấy SurveyId tại đây.YES

    keyhash

    String

    Là kết quả Secret Key qua hàm hash MD5. Lấy Key Hash tại đây.

    		YES
    Kết quả trả về
    Định dạng:
    JSON
    Thành công
    Response = {
    success: {type: Boolean},
    data: [{
    questionId: {type: number},
    questionTitle: {type: String},
    type: {type: String},
    textAnswers: [{
    value: {type: String},
    }],
    statistics: [{
    answerId: {type: number},
    value: {type: String},
    count: {type: number},
    }],
    totalResponses: {type: number},
    }],
    numberCurrentSurveyDoers: {type: Number}, // Number of Respondents
    }
    Thất bại
    Response = {
    success: {type: Boolean},
    message: {type: String},
    }