Kahoot! raporlar API kılavuzu

Güncellenme

Kahoot! raporlar API'yi nasıl kullanacağını merak mı ediyorsun? İşte başlamak için bilmen gereken her şey.

Kısayollar:

Kahoot API Hakkında 

Kahoot API, OpenAPI'yi takip eden bir REST API'dir. Kaynakların ve uç noktaların ayrıntıları da dâhil olmak üzere tüm API belgelerimizi https://results.kahoot.com/swagger/ adresinden inceleyebilirsin. 

Kahoot API'ye çağrı yapmak için şirketinin yetkili erişime ihtiyacı vardır. API, API'ler hakkında bilgi sahibi olan bir veri ekibi veya geliştiricilere sahip müşteriler için mükemmeldir. Bu API ile şirketin, oyun bittikten sonra son 90 gün içinde aşağıda listelenen tüm verilere erişebilecek. Müşterinin verileri sistemimizden çektiği zamanla ilgili olarak verilerimize zaman damgası koyuyor ve başlangıç ve bitiş tarihlerini destekliyoruz. 

Kahoot API oyun, kullanıcılar, katılımcılar, kurumlar ve kurum tarafından oluşturulan kahoot'larla ilgili bilgiler hakkında rapor sunar. Bazen, platform üzerinden sunduğumuz raporlar çok fazla yarar sağlamayabilir. Ürünü sık kullanan veya çok sayıda katılımcısı olan ve etkinliklerini takip etmek isteyen müşteriler için ise API, bunu ölçeklenebilir bir şekilde yapmanın harika bir yoludur.

API'ye erişme

API yetkilendirilmesi sadece belirli, en yüksek seviye planlardaki müşterilere sunulmaktadır. Planını yükseltmek veya yetkilendirme sürecini başlatmakla ilgileniyorsan müşteri başarısı yöneticine ulaş.

API ile kimlik doğrulama

API için kimlik doğrulama, API'ye yapılan her isteğin Kimlik Doğrulama üst bilgisinde sağlanması gereken bir JWT taşıyıcı belirtecinin kullanılması ile gerçekleştirilir. Belirteçlerin süresi bir saat ile sınırlıdır ve bu sürenin sonunda yeni bir belirteç alınması gerekir.

Bir belirteç almak için önce müşteri başarısı yöneticin tarafından sağlanacak bir istemci kimliğine ve gizli anahtara ihtiyacın vardır. Bu kimlik bilgilerine sahip olduğunda aşağıda açıklandığı gibi kimlik doğrulama sunucumuzdan belirteci istemen gerekir.

URL

https://access-2.kahoot.com/auth/realms/kahoot-api/protocol/openid-connect/token

Http Yöntemi

PUT

Yetkilendirme Üst Bilgisi

Kahoot tarafından sağlanan kimlik bilgilerini kullanarak temel yetkilendirme başlığı sağlamalıdır.

İçerik Türü Üst Bilgisi

application/x-www-form-urlencoded

İstek Gövdesi

grant_type=client_credentials

 

Curl ile yapılabilecek örnek bir istek aşağıda gösterilmiştir:

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

 

İstekten gelen yanıt aşağıdaki yapıda olacaktır:

{
"access_token": "<token to use in api requests>",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}

 

API'de düzgün bir şekilde kimlik doğrulaması yapmak için yukarıdaki yanıtta yer alan access_token değerini API'ye yaptığın isteklerde taşıyıcı belirteci olarak kullanman gerekir. Bu, tüm isteklerin Yetkilendirme üst bilgisinin “Bearer: <token>” biçiminde bir değere sahip olması gerektiği anlamına gelir. API'ye doğru bir şekilde geçerli bir belirteç sağlamadıysan 401 yanıtı alınır.

Sözlük

Terim

Açıklama

Canlı Oyun

Bir kahoot yüz yüze oynandığında.

Yarışma

Bir kahoot eş zamansız olarak oynandığında.

puanlar

Tamsayı değeri. Oyuncunun bu soru için aldığı puan sayısı.

cevaplar

Bir soru için gönderilen bir dizi cevap.

alındı, zaman aşımı

Soru için verilen cevap.

zaman aşımı

Bir kullanıcı bir soruya cevap vermediğinde.

Blok

Belirli soru türleri her zaman 'block' olarak adlandırılır - örneğin Doğru/Yanlış soru türü TrueFalseBlock olarak ve Beyin Fırtınası soru türü BrainstormBlock olarak adlandırılır.

kahoot

Asıl kahoot. Bu, bir oyundan veya (kahoot gerçekten oynandığında dediğimiz) oyun oturumundan farklıdır.

oyun

Kahoot oynandığında.

oyun oturumu

Benzersiz bir oyun örneği.

sunucu

Oyunu başlatan kullanıcı.

kahoot sürümü

Eğer kahoot'lar değiştirilirse, o kahoot'un farklı sürümlerini saklarız. Bir kahoot'un farklı sürümleri oynanabilir ve dolayısıyla saklanan cevaplar farklı olabilir. Kahoot'un 0 ile gösterilen sürümünün, sürümü oluşturulmamış demektir.

kurs

Bazı oyunlar kurslara bağlıdır, bu durumda bir kurs kimliği verilir.

Blok dizini - Kahoot

Oyunun ilişkili kahoot'ta özgün şekilde göründüğü dizin (0 tabanlı).

Blok dizini - Oyun

Oyunun oyun oturumu sırasında göründüğü dizin (0 tabanlı).

Soruların karışık sırada kullanılması durumunda blockIndexInKahoot'tan farklı olabilir.

sorular

Kahoot'taki soruların listesi.

Beyin fırtınası (soru türü)

Katılımcıların fikirlerini gönderdiği ve oyladığı açık uçlu soru türü.

İşaret Bırak (soru türü)

Katılımcıların bir resim üzerine işaret bırakabilecekleri puansız soru.

Oylama (soru türü)

Oyuncuların bir soruda 6 farklı seçenek seçebileceği puansız soru.

Çok Cevaplı Quiz (soru türü)

Oyunculara bir soruda seçebilecekleri birkaç cevap seçeneği sun.

Açık Uçlu (soru türü)

Oyuncuların uzun metin yanıtı biçiminde cevap vereceği soru.

Puzzle (soru türü)

Oyuncuların cevapları doğru sırada yerleştirdiği soru.

Kaydırmalı (soru türü)

Katılımcılar bir aralıktaki doğru sayıyı tahmin eder.

Doğru/Yanlış (soru türü)

Katılımcılar bir ifadenin doğru mu yanlış mı olduğuna karar verir.

Kısa Cevaplı (soru türü)

Katılımcılar kısa bir metinle cevap verir.

Kelime Bulutu (soru türü)

Kısa serbest biçimli oylama yanıtlarını toplayan soru.

Yaygın İstekler - Nasıl Yapılır Kılavuzu

Bir oyunun katılımcılarını listeleme

"Katılımcı" kimdir? 

Aşağıdaki adımlar oyuna giren tüm oyuncuların nasıl listeleneceğini açıklamaktadır. 

Lütfen "katılmanın" "aktif olarak oynamak" ile aynı şey olmadığını unutma. Oyuna katılıp bağlantı sorunları ya da dikkatini verememe nedeniyle hiçbir soruya cevap verilemeyebilir. Bu tür katılımcılar yine de sonuçlara dâhil edilecektir. 

Oyunu bul 

Belirli bir zaman diliminde kurumunda oynanan tüm oyunları listelemek için GET /v1/organisations/{organisationId}/games?limit={limit}&startedSince={date} komutunu çalıştır. Başka bir sonuç sayfasının mevcut ve gerekli olması durumunda imleç sorgu parametresi ekle.

Örnek bir çıktı, oyun oturumlarının bir listesini içerecektir: 

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

Sonuçlarda oturumu bul ve gameSessionId olduğunu unutma. 

Oyun katılımcılarını listele 

Oyuna katılan tüm katılımcıları listelemek için GET /v1/organisations/{organisationId}/games/{gameSessionId}/participants komutunu çalıştır.

Örnek sonuç: 

[ 

 { 

 "participantId": 1234, 

 "nickname": "Johnny", 

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

 }, 

 { 

 "participantId": 4321, 

 "nickname": "Robert", 

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

 } 

]

participantId ve userId arasındaki fark ne? 

  • participantId bir tam sayıdır ve oyun seçeneklerinden bağımsız olarak her zaman mevcuttur.
  • participantId sadece bu oyun oturumundaki belirli bir oyuncuyu tanımlar. Aynı participantId farklı bir oyun oturumunda farklı bir kişiyi ifade edebilir ve  genellikle de eder. 
  • userId sadece Oyuncu Tanımlayıcı seçeneğinin etkin olduğu oyunlarda yer alır. Oyunculardan takma adın yanı sıra e-posta gibi kimlik bilgilerini de vermeleri bu durumda istenir. Ya da e-postaları kullanılarak oyuna davet edildiklerinde.
  • userId aynı kişinin birden fazla oyun oturumunda izlenmesini mümkün kılar.

Katılımcının e-posta adresini alma 

GET /v1/organisations/{organisationId}/users/{userId} komutunu çalıştır. Getirilen nesne e-posta özelliğini içerecektir. 

Soruların en az %80'ini doğru yanıtlayan katılımcıları listeleme 

Oyunu bul

Oyunun bulunmasıyla ilgili bölüme bak. 

Oynanan kahoot ile ilgili bilgileri bul. İki bölümden oluşur: 

  1. id - Oynanan kahoot'a başvuran UUID 
  1. version - kahoot, oyun oynandıktan sonra oluşturucu tarafından düzenlenmiş olabilir. Bu her gerçekleştiğinde sürüm özelliği artırılır. Bu, cevapların doğru verilere başvuruda bulunmasını sağlar.  
{ 

 // other propperties 

 "kahootIdentifier": { 

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

 "version": 5 

 }, 

}

Katılımcıları al

Katılımcıların listelenmesi ile ilgili bölüme bak.

Kahoot verilerini al 

GET /v1/organisations/{organisationId}/kahoots/{kahootId}/versions/{version} komutunu çalıştırarak kahootIdentifier.id ve kahootIdentifier.version özelliklerine dayalı sorgu parametrelerine sahip kahoot'u al. 

Sonuç, varsa katılımcılar için sunulan cevap seçenekleri ile birlikte kahoot'un içerdiği tüm soruları (blokları) içerecektir. Sorular ve cevap seçeneklerine daha sonra cevap belgeleri tarafından başvurulacaktır. 

Örnek sorular: 

{ 

 "kahootIdentifier": { 

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

 "version": 5 

 }, 

 "title": "Kahoot title", 

 "description": "This kahoot is about ...", 

 "questions": [ 

 { 

 "contentType": "CONTENT" 

 "blockIndex": 0 

 "title": "This is the company presentation" 

 "description": "Some slide contents" 

 }, 

 { 

 "contentType": "SINGLE_SELECT_QUIZ" 

 "blockIndex": 1 

 "question": "Who is our biggest customer?" 

 "choices": [ 

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

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

 ] 

 }, 

 ] 

}

Tüm cevapları al 

Oyunu ararken alınan gameSessi onId (oyun bulma bölümüne bak) ve kahoot'taki sorunun dizini olan blockIndex ögelerini kullanarak GET /v1/organisations/{organisationId}/games/{gameSessionId}/blocks/{blockIndex}/answers komutunu çalıştır. Soru olmayanlar (içerik, diğer adıyla slaytlar) dışında oynanan tüm bloklar (sorular) üzerinde yineleme yapılması gerekir. 

Aşağıdaki örnekte katılımcının part cipantId=1234 (katılımcıları listeleme örneğinde olduğu gibi "Johnny" takma adı) ile tanımlandığı ve doğru olan ikinci seçeneği seçtiği, tek cevaplı bir quiz olan kahoot'un ikinci bloğuna verilen bir cevap gösterilmektedir. Ayrıca "Robert" takma adlı katılımcının soruyu süre sınırı içinde cevaplamayı başaramadığını da görebiliyoruz.

{ 

 "blockIndexInKahoot": 1 

 "answers": [ 

 { 

 "participantId": 1234, 

 "answerStatus": "RECEIVED", 

 "answer": { 

 "type": "SINGLE_SELECT_QUIZ", 

 "choice": 1, 

 "correct": true, 

 "points": 900 

 } 

 }, 

 { 

 "participantId": 4321, 

 "answerStatus": "TIMEOUT" 

 }, 

 ] 

}

Seçimin ve katılımcının takma adının ne olduğunu öğrenmek için önceki bölümlerde sözü edilen ilgili kahoot verilerine ve katılımcı verilerine başvurulması gerekir. 

404 alınırsa ne olur? 

Belirli bir bloga yönelik cevaplar aşağıdaki durumlarda eksik olabilir: 

  1. Belirtilen soru (blok) CONTENT türündedir. Bunlara "cevap verme" işlemi iyi tanımlanmamıştır. 
  2. Oyun bir atanan kahoot olarak oynanmış ve katılımcıların hiçbiri 3. soruya ulaşamamıştır. 
  3. Oyun sırasında bir ağ sorunu meydana gelmiş ve cevap kaydedilmemiştir (nadir bir durumdur, ancak gerçekleşmesi mümkündür).

Her durumda istemcilerin cevap verilerinin eksik olabileceği konusunda hazırlıklı olmaları gerekir. 

Cevapları katılımcılarla eşleştirme 

Cevaplar sadece bilgileri ayrı uç noktanın yanıt yükünde bulunan katılımcıların bağlantılarını içerir ("Oyun katılımcılarını listele" bölümüne bak). Bu bağlantı, her iki yükte mevcut olan participantId özelliğidir. 

"Doğru cevap" ne demek? 

Bazı soru türlerinde "yanlış" ve "doğru" cevap durumu arasında gri bir alan bulunmaktadır.

Çok cevaplı quiz soruları 

CORRECT - katılımcı tüm doğru seçenekleri seçmiş ve yanlış seçeneklerden hiçbirini seçmemiştir 

PARTIALLY_CORRECT - katılımcı doğru seçeneklerden en az birini seçmiş ve yanlış seçeneklerden hiçbirini seçmemiştir WRONG - katılımcı yanlış seçeneklerden en az birini seçmiştir 

Kaydırmalı sorular 

CORRECT - katılımcı kaydırı üzerinde doğru değeri seçmiştir 

ALMOST_CORRECT - katılımcı tam olmayan ancak kahoot oluşturucu tarafından belirlenen tolerans içinde yer alan bir değer seçmiştir WRONG - seçilen değer tolerans aralığının dışındadır

Diğer tüm sorular 

Doğru veya yanlış cevabı olabilecek diğer tüm sorular için sadece iki seçenek vardır: CORRECT ve WRONG.

Zaman aşımı ve doğru cevap arasındaki ilişki 

TIMEOUT 'a eşit durumda olan ParticipantAnswer nesnelerini answer özelliğine sahip olmayacaktır, bu nedenle ne "doğru" ne de "yanlış" olarak değerlendirilirler.  Bunlarla ilgili ne yapılacağına karar vermek kullanıcıya bağlıdır. Oyun sırasında bunlara her zaman sıfır puan atanır.

İlgili makaleler

Raporlar

İlgili makaleler

Raporlar

0 yorum

Yorum yazmak için lütfen oturum açın: oturum aç.