Panduan untuk Kahoot! laporan API

Diperbarui

Ingin tahu cara menggunakan Kahoot! laporan API? Berikut ini semua yang perlu Anda ketahui untuk memulai.

Jalan pintas:

Tentang API Kahoot 

API Kahoot adalah API REST yang mengikuti OpenAPI. Anda dapat meninjau semua dokumentasi API kami, termasuk detail sumber daya dan titik akhir di https://results.kahoot.com/swagger/. 

Untuk melakukan panggilan ke Kahoot API, perusahaan Anda akan memerlukan akses resmi. API paling cocok untuk pelanggan yang memiliki tim data atau pengembang yang terbiasa dengan API. Dengan API ini, perusahaan Anda akan dapat mengakses semua data yang tercantum di bawah ini dalam 90 hari terakhir setelah permainan selesai. Kami memberi stempel waktu pada data kami dan mendukung tanggal mulai dan berakhirnya ketika pelanggan menarik data dari sistem kami. 

Kahoot API melaporkan informasi yang berkaitan dengan permainan, pengguna, peserta, organisasi, dan kahoot yang dibuat oleh organisasi. Terkadang, pelaporan kami di platform hanya bisa melakukan banyak hal. Untuk pelanggan yang sering menggunakan produk atau dengan jumlah peserta yang banyak, dan ingin melacak aktivitas mereka, API adalah cara terbaik untuk melakukannya secara terukur.

Cara mengakses API

Otorisasi API hanya tersedia untuk pelanggan pada paket tingkat tertinggi tertentu. Hubungi manajer kesuksesan pelanggan Anda jika Anda tertarik untuk meningkatkan atau memulai proses otorisasi.

Mengautentikasi dengan API

Otentikasi untuk API dicapai melalui penggunaan token pembawa JWT yang harus disediakan di header Otentikasi setiap permintaan ke API. Token memiliki batas waktu hingga satu jam, setelah itu token baru harus diperoleh.

Untuk mendapatkan token, Anda memerlukan id klien dan rahasia yang akan diberikan oleh manajer kesuksesan pelanggan Anda. Setelah Anda memiliki kredensial ini, Anda harus meminta token dari server autentikasi kami seperti yang dijelaskan di bawah ini.

URL https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token
Metode Http PUT
Tajuk Otorisasi Harus memberikan judul otorisasi dasar menggunakan kredensial yang disediakan oleh kahoot.
Header Jenis Konten application/x-www-form-urlencoded
Isi Permohonan jenis_hibah = kredensial_klien

 

Contoh permintaan yang dapat dibuat dengan curl ditunjukkan di bawah ini:

curl --request POST \
--url https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token \
--header 'Otorisasi: Basic <digest>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type = client_credentials

 

Tanggapan dari permintaan akan memiliki struktur sebagai berikut:

{
"access_token": "<token untuk digunakan dalam permintaan api>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "profil email"
}

 

Untuk mengautentikasi API dengan benar, Anda harus menggunakan nilai access_token pada respons di atas sebagai token pembawa dalam permintaan Anda ke API. Ini berarti header Otorisasi dari semua permintaan harus memiliki nilai dalam bentuk "Pembawa: <token>". Jika Anda belum memberikan token yang valid dengan benar ke API, respons 401 akan dikembalikan.

Daftar Istilah

Istilah Deskripsi
Permainan Langsung Ketika kahoot dimainkan secara langsung.
Tantangan Apabila kahoot dimainkan secara asinkron.
poin Nilai bilangan bulat. Jumlah poin yang diperoleh pemain untuk pertanyaan ini.
jawaban Satu set jawaban yang dikirimkan untuk sebuah pertanyaan.
diterima, batas waktu Jawaban yang diberikan untuk pertanyaan tersebut.
batas waktu Ketika pengguna tidak memberikan jawaban atas sebuah pertanyaan.
Blokir Jenis pertanyaan tertentu selalu disebut sebagai 'blok' misalnya - jenis pertanyaan Benar atau Salah disebut TrueFalseBlock dan jenis pertanyaan Curah Pendapat disebut sebagai BrainstormBlock.
kahoot Kahoot yang sebenarnya. Ini berbeda dengan sesi permainan atau game (sebutan untuk sesi ketika kahoot benar-benar dimainkan).
permainan Ketika kahoot dimainkan.
sesi permainan Contoh permainan yang unik.
tuan rumah Pengguna yang meluncurkan game.
versi kahoot Jika kahoot dimodifikasi, kami menyimpan versi yang berbeda dari kahoot tersebut. Versi yang berbeda dari sebuah kahoot dapat dimainkan dan dengan demikian menyimpan jawaban yang berbeda. Versi kahoot di mana 0 diindikasikan tidak memiliki versi.
tentu saja Beberapa permainan terkait dengan kursus, jika demikian, akan ada ID kursus yang disediakan.
Indeks blokir - Kahoot Indeks di mana game pertama kali muncul di kahoot terkait (berbasis 0).
Indeks blok - Permainan

Indeks di mana permainan muncul selama sesi permainan (berbasis 0).

Dapat berbeda dengan blockIndexInKahoot jika urutan pertanyaan yang digunakan acak.
pertanyaan Daftar pertanyaan dalam kahoot.
Curah pendapat (jenis pertanyaan) Tipe pertanyaan terbuka di mana peserta mengirimkan ide dan memberikan suara.
Jatuhkan Pin (jenis pertanyaan) Pertanyaan tanpa titik di mana peserta dapat menjatuhkan pin pada gambar.
Jajak pendapat (jenis pertanyaan) Pertanyaan tanpa poin di mana pemain memilih hingga 6 opsi dalam satu pertanyaan.
Kuis Pilihan Ganda (tipe pertanyaan) Berikan pemain beberapa jawaban untuk dipilih dalam sebuah pertanyaan.
Open Ended (tipe pertanyaan) Pertanyaan untuk dijawab oleh pemain dalam bentuk teks yang panjang.
Teka-teki (jenis pertanyaan) Pertanyaan yang mengharuskan pemain menjawab dengan urutan yang benar.
Penggeser (jenis pertanyaan) Peserta menebak angka yang benar dalam suatu rentang.
Benar Salah (tipe pertanyaan) Peserta memutuskan apakah suatu pernyataan itu benar atau salah.
Ketik Jawaban (jenis pertanyaan) Peserta menjawab dengan teks isian singkat.
Awan Kata (jenis pertanyaan) Pertanyaan yang mengumpulkan pertanyaan jajak pendapat singkat berbentuk bebas.

Permintaan Umum - Cara Memandu

Cara membuat daftar peserta permainan

Siapa yang dimaksud dengan "peserta"? 

Langkah-langkah berikut ini menjelaskan cara membuat daftar semua pemain yang masuk ke dalam permainan. 

Harap diperhatikan bahwa "bergabung" tidak sama dengan "aktif bermain". Anda dapat bergabung dalam permainan dan tidak menjawab pertanyaan apa pun karena masalah koneksi atau tidak memperhatikan. Peserta seperti itu tetap akan diikutsertakan dalam hasil. 

Temukan permainannya 

Panggil GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} untuk membuat daftar semua game yang dimainkan di organisasi Anda dalam jangka waktu tertentu. Tambahkanparameter kueri kursor jika halaman hasil lain tersedia dan dibutuhkan.

Contoh output akan berisi daftar sesi permainan: 

{
data: [
"gameSessionId": "3c28c370-0407-416f-a44f-087715b4ea89", "hostUserId": "70feec9e-1ee3-4e35-8d6b-0fe44d9f2358", "kahootIdentifier": {
 "id": "3c28c370-0407-416f-a44f-087715b4ea89", 
 "version": 5 
},
"startTime": 1667928438123,
}
],
kursor: "abcxyz"
}

Temukan sesi dalam hasil dan ingatlah gameSessionId-nya. 

Daftar peserta permainan 

Memanggil GET /v1/organisasi/{organisationId}/games/{gameSessionId}/peserta untuk membuat daftar semua peserta yang bergabung dalam permainan.

Hasil sampel: 

[

{

"participantId": 1234,

"nickname": "Johnny",

"userId": "f7e9a793-f223-4f2e-ad79-8bfa546a7180"

},

{

"participantId": 4321,

"nickname": "Robert",

"userId": "a9555f0c-68b2-41b1-a540-49c34e15242e"

}

]

Apa perbedaan antara participantId dan userId? 

  • participantId adalah sebuah bilangan bulat dan selalu ada terlepas dari opsi permainan.
  • participantId mengidentifikasi pemain tertentu dalam sesi permainan ini saja. participantId yang sama di sesi permainan yang berbeda dapat dan biasanya merujuk pada orang yang berbeda. 
  • userId hanya disertakan dalam game dengan opsi Pengenal Pemain yang diaktifkan. Saat itulah para pemain diminta untuk memberikan identitas mereka seperti email selain nama panggilan. Atau ketika mereka diundang ke permainan menggunakan email mereka.
  • userId memungkinkan untuk melacak orang yang sama di beberapa sesi permainan.

Cara mendapatkan alamat email peserta 

Panggil GET /v1/organisations/{organisationId}/users/{userId} Objek yang dikembalikan akan berisi propertiemail .  

Cara membuat daftar peserta yang menjawab setidaknya 80% pertanyaan dengan benar 

Temukan permainannya

Lihat bagian tentang cara menemukan permainan. 

Temukan informasi tentang kahoot yang dimainkan. Alat ini memiliki dua bagian: 

  1. id - UUID merujuk pada kahoot yang dimainkan
  1. versi - kahoot mungkin telah diedit oleh pembuatnya setelah permainan berlangsung. Setiap kali hal itu terjadi, properti versi akan bertambah. Hal ini memastikan bahwa jawaban mengacu pada data yang benar.  
{

// other propperties

"kahootIdentifier": {

"id": "3c28c370-0407-416f-a44f-087715b4ea89",

"version": 5

},

}

Dapatkan peserta

Lihat bagian tentang daftar peserta.

Dapatkan data kahoot 

Panggil GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} untuk mendapatkan kahoot dengan parameter kueri berdasarkan propertikahootIdentifier.id dan kahootIdentifier.version .  

Hasilnya akan berisi semua pertanyaan (blok) yang terdapat dalam kahoot bersama dengan pilihan jawaban yang tersedia bagi para peserta jika ada. Pertanyaan dan pilihan jawaban akan dirujuk oleh dokumen jawaban. 

Contoh pertanyaan: 

{

"kahootIdentifier": {

"id": "3c28c370-0407-416f-a44f-087715b4ea89",

"version": 5

},

"title": "Judul Kahoot",

"deskripsi": "Kahoot ini adalah tentang...",

"pertanyaan": [

{

"contentType": "CONTENT"

"blockIndex": 0

"title": "Ini adalah presentasi perusahaan"

"description": "Beberapa isi slide"

},

{

"contentType": "SINGLE_SELECT_QUIZ"

"blockIndex": 1

"pertanyaan": "Siapa pelanggan terbesar kami?" 

 "pilihan": [

{"answerText": "Very Big Corp. of America", "correct": false},

{"answerText": "Skynet", "correct": true}

]

},

]

}

Dapatkan semua jawaban 

Panggil GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/jawaban menggunakan gameSessi onId yang didapat saat mencari game (lihat bagian cari game) dan blockIndex sebagai indeks pertanyaan dalam kahoot. Kita perlu mengulang semua blok (pertanyaan) yang dimainkan, tidak termasuk yang bukan pertanyaan sama sekali (konten alias soal). slide). 

Contoh berikut ini menunjukkan jawaban untuk blok kedua dari kahoot yang merupakan kuis pilihan tunggal, di mana peserta diidentifikasi dengan parti cipantId = 1234 (nama panggilan "Johnny" seperti pada contoh peserta yang terdaftar) dan memilih pilihan kedua yang kebetulan benar. Kita juga dapat melihat bahwa peserta dengan nama panggilan "Robert" tidak berhasil menjawab pertanyaan dalam batas waktu yang ditentukan.

{

"blockIndexInKahoot": 1

"answers": [

{

"participantId": 1234,

"answerStatus": "DITERIMA",

"jawaban": {

"type": "SINGLE_SELECT_QUIZ",

"pilihan": 1,

"correct": true,

"points": 900

}

},

{

"participantId": 4321,

"answerStatus": "TIMEOUT"

},

]

}

Untuk mengetahui apa yang menjadi pilihan dan apa nama panggilan peserta, kita perlu merujuk pada data kahoot terkait dan data peserta yang disebutkan di bagian sebelumnya. 

Bagaimana jika 404 dikembalikan? 

Jawaban untuk blok tertentu dapat hilang dalam kasus-kasus berikut: 

  1. Pertanyaan yang diberikan (blok) bertipe KONTEN. "Menjawab" pertanyaan-pertanyaan tersebut tidak terdefinisi dengan baik. 
  2. Permainan ini dimainkan sebagai tugas dan tidak ada peserta yang mencapai pertanyaan ke-3. 
  3. Ada masalah jaringan selama permainan dan jawabannya tidak tersimpan (kasus yang jarang terjadi, tetapi mungkin saja terjadi).

Bagaimanapun, klien harus siap bahwa data jawaban mungkin tidak ada di sana. 

Mencocokkan jawaban dengan peserta 

Jawaban hanya berisi tautan ke peserta yang rinciannya terdapat dalam muatan respons titik akhir yang terpisah (lihat bagian "Daftar peserta permainan"). Tautan tersebut adalah participantId properti yang ada di kedua muatan. 

Apa yang dimaksud dengan "jawaban yang benar"? 

Pada beberapa jenis pertanyaan, ada beberapa area abu-abu antara status jawaban "salah" dan "benar".

Pertanyaan kuis pilihan ganda 

BENAR - peserta memilih semua pilihan yang benar dan tidak ada pilihan yang salah

SEBAGIAN_BENAR - peserta memilih setidaknya satu dari pilihan yang benar dan tidak ada pilihan yang salah SALAH - peserta memilih setidaknya satu pilihan yang salah

Pertanyaan slider 

BENAR - peserta memilih nilai yang benar pada penggeser

HAMPIR BENAR - peserta memilih nilai yang tidak tepat, tetapi masih dalam toleransi yang ditetapkan oleh pembuat kahoot SALAH - nilai yang dipilih berada di luar rentang toleransi

Semua pertanyaan lainnya 

Untuk semua pertanyaan lain yang bisa memiliki jawaban benar atau salah, hanya ada dua pilihan: BENAR dan SALAH.

Hubungan antara waktu habis dan jawaban yang benar 

Objek ParticipantAnswer dengan status sama dengan TIMEOUT tidak akan memiliki propertijawaban , sehingga tidak akan bernilai "benar" atau "salah".  Terserah kepada pengguna untuk memutuskan bagaimana memperlakukannya. Mereka selalu diberi nilai nol selama pertandingan.

 

Menyajikan data API.

Ada banyak cara untuk menyajikan data API yang diekstrak. Berikut adalah contoh dari Kahoot! data yang divisualisasikan di Power BI.

Contoh data API di Power BI.png

💡 Menemukan ini bermanfaat? Berlanggananlah ke saluran Youtube kami untuk mendapatkan lebih banyak tips dan Kahoot! tutorial!

0 komentar

Harap masuk untuk memberikan komentar.