Bölüm 4 GET

join – Toplantıya Katıl

join uç noktası, bir kullanıcının çalışmakta olan bir BigBlueButton toplantısına girmesine olanak tanıyan bir URL üretir. Varsayılan olarak tarayıcı doğrudan BBB istemcisine yönlendirilir. redirect, false olarak ayarlandığında bunun yerine katılma URL'si ve oturum belirteci içeren bir XML yanıtı döndürülür.

Uç Nokta

GET https://api-guide.bbbserver.com/bigbluebutton/api/join?<parameters>&checksum=replace-with-checksum

join çağrısı, son kullanıcının tarayıcısında doğrudan çağrılan tek API uç noktasıdır (bir yönlendirme URL'si olarak). Diğer tüm API çağrıları sunucu tarafında yapılır.

Gerekli Parametreler

Parametre Tür Açıklama
meetingID String Gerekli. Katılınacak toplantının tanımlayıcısı.
fullName String Gerekli. Kullanıcının toplantıda görünen adı.
role Enum Gerekli. Kullanıcı rolü: MODERATOR veya VIEWER (büyük/küçük harfe duyarsız). BBB 3.0+

Kullanımdan Kaldırılmış Parametreler

Parametre Tür Açıklama
password String Kullanımdan kaldırıldı BBB 3.0 sürümünden beri kullanımdan kaldırılmıştır. Parola aracılığıyla rol ataması (create içindeki attendeePW/moderatorPW). Yerine role kullanılır.

İsteğe Bağlı Parametreler

Parametre Tür Varsayılan Açıklama
createTime Number (Long) — create yanıtındaki zaman damgası. join URL'si oluşturulduktan sonra yeniden oluşturulmuş bir toplantıya katılmayı engeller.
userID String — Uygulamaya özgü kullanıcı kimliği. getMeetingInfo ve webhooks içinde döndürülür.
avatarURL String — Kullanıcı için bir avatar görselinin URL'si.
webcamBackgroundURL String — Özel bir web kamerası arka plan görselinin URL'si.
firstName String — Ad (görüntüleme için değil, sıralama için kullanılır).
lastName String — Soyad (görüntüleme için değil, sıralama için kullanılır).
redirect Boolean true false olarak ayarlandığında, tarayıcı yönlendirmesi yerine bir XML yanıtı döndürülür.
errorRedirectUrl String — Hatalarda yönlendirilecek alternatif URL (varsayılan hata sayfası yerine).
logoutURL String — Çıkıştan sonra yönlendirilecek URL. create içindeki değeri geçersiz kılar.
guest Boolean false Kullanıcıyı misafir olarak işaretler. Toplantının guestPolicy ayarına tabidir.
bot Boolean false Kullanıcıyı otomatik bir aracı olarak işaretler.
excludeFromDashboard Boolean false Kullanıcıyı öğrenme analitiği panosunun dışında tutar.
enforceLayout Enum — Bu kullanıcı için belirli bir düzeni zorunlu kılar. Olası değerler: UNIFIED_LAYOUT, CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
‎⚠ Belgelenmemiş Resmi belgeler bu değeri yanlışlıkla PARTICIPANTS_CHAT_ONLY olarak listeler (_AND_ olmadan).
auth Boolean (koşullu) ‎⚠ Belgelenmemiş Kullanıcıyı kimliği doğrulanmış olarak işaretler. Koşullu mantık: guest belirtilmemişse, auth varsayılan olarak true olur. guest=true belirtilirse, auth açıkça ayarlanmadıkça varsayılan olarak false olur.
defaultLayout String — ‎⚠ Belgelenmemiş Bu kullanıcı için varsayılan düzen. create çağrısındaki meetingLayout ile aynı değerlere sahiptir.
sessionName String — ‎⚠ Belgelenmemiş Özel oturum adı. Yalnızca existingUserID ile birlikte etkilidir.
existingUserID String — ‎⚠ Belgelenmemiş Mevcut bir oturumla yeniden katılmak veya yeniden bağlanmak için dahili kullanıcı kimliği.
replaceSessionToken String — ‎⚠ Belgelenmemiş Değiştirilecek oturumun belirteci (existingUserID ile kullanıldığında).

Userdata Parametreleri

join çağrılırken özel verileri userdata-= parametreleri olarak iletebilirsiniz. Bunlar istemcide kullanılabilir hale getirilir ve eklenti davranışını veya istemci ayarlarını kullanıcı bazında kontrol edebilir.

Belirli userdata anahtarları, sunucu tarafında bir engelleme listesi (getJoinUrlUserdataBlocklist) aracılığıyla engellenebilir.

Örnek İstek

GET https://api-guide.bbbserver.com/bigbluebutton/api/join?meetingID=replace-with-meeting-id&fullName=John+Doe&role=VIEWER&redirect=false&checksum=replace-with-checksum

Örnek Yanıt (redirect=false)

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>successfullyJoined</messageKey>
  <message>You have joined successfully.</message>
    <meeting_id>replace-with-internal-meeting-id</meeting_id>
    <user_id>replace-with-user-id</user_id>
        <auth_token>replace-with-auth-token</auth_token>
        <session_token>replace-with-session-token</session_token>
        <url>https://api-guide.bbbserver.com/client/BigBlueButton.html?sessionToken=replace-with-session-token</url>
</response>

Hata Yanıtları

messageKey Anlamı
invalidMeetingIdentifier Toplantı mevcut değil.
meetingForciblyEnded Toplantı zorla sonlandırıldı.
maxParticipantsReached Katılımcı sınırına ulaşıldı.
guestDeniedAccess Misafirin erişimi reddedildi.
invalidPassword Parola geçersiz.
checksumError checksum geçersiz.
mismatchCreateTimeParam createTime toplantıyla eşleşmiyor.
userNotFound Bu kimlikle etkin bir kullanıcı bulunamadı (existingUserID kullanılırken).

Katılma URL Doğrulaması için createTime Kullanımı

createTime parametresi, eski join URL'lerine karşı bir güvence görevi görür:

Bir toplantı oluşturulur ve createTime: 1715261728123 döndürülür.

Join URL, createTime=1715261728123 ile oluşturulur.

Toplantı sona erer ve yeni bir createTime ile yeniden oluşturulur.

Önceki createTime değerini içeren eski join URL reddedilir.

Bu, eski davet bağlantılarına sahip kullanıcıların aynı meetingID'yi yeniden kullanan yeni bir toplantıya girmesini önler.

bbbserver.de üzerinde katılma URL'si her zaman doğru checksum ve parametrelerle sunucu tarafında oluşturulur. Katılma URL'lerini manuel olarak oluşturmanız gerekmez.

Güvenlik İpuçları

Katılma URL'lerini hesaplamak için shared secret değerini istemci tarafında asla açığa çıkarmayın. Katılma URL'lerini her zaman sunucu tarafında oluşturun ve istemciye iletin.

  • Oluşturulan katılma URL'si checksum içerir ve yalnızca bir kez kullanılmalıdır.
  • Join URL'leri sunucu tarafında oluşturulmalı ve istemciye iletilmelidir.
  • Hassas toplantılar için, guest=true ile birlikte guestPolicy=ASK_MODERATOR kullanın.

password değerinden role değerine geçiş, BBB 3.0 içindeki en önemli geriye dönük uyumsuz değişikliklerden biridir. Entegrasyonunuzu buna göre güncellediğinizden emin olun.

Sıkça Sorulan Sorular

BBB 3.0 ve sonrasında, role parametresi (MODERATOR veya VIEWER), önceki sürümlerde kullanılan parola tabanlı rol atamasının yerini alır. password parametresi kullanımdan kaldırılmıştır ve yeni entegrasyonlarda artık kullanılmamalıdır.

Tarayıcıyı toplantıya yönlendirmek yerine sunucu, katılma URL'si ve oturum belirteci içeren bir XML yanıtı döndürür. Bu, yanıtı incelemesi veya oturum belirtecini programatik olarak yönetmesi gereken sunucu tarafı entegrasyonları için yararlıdır.

Evet. Yeniden bağlanmak için önceki oturumdaki dahili kullanıcı kimliğiyle existingUserID parametresini kullanın. Eski oturumun yerine geçmesi için replaceSessionToken da iletebilirsiniz. Bu parametrelerin belgelenmemiş olduğunu ve haber verilmeksizin değişebileceğini unutmayın.

guest, true olarak ayarlandığında kullanıcı misafir olarak işaretlenir ve toplantı oluşturulurken tanımlanan guestPolicy politikasına tabi olur. Örneğin, ASK_MODERATOR ile kullanıcı içeri girmeden önce moderatörün misafiri onaylaması gerekir.

Userdata parametreleri (userdata-=), özel verileri kullanıcı bazında toplantı istemcisine iletmenize olanak tanır. Bunlar istemci davranışını yapılandırmak, eklentilere bilgi aktarmak veya kullanıcı deneyimini özelleştirmek için kullanılabilir.

Bu hata, katılma URL'nizdeki createTime değerinin şu anda çalışan toplantının createTime değeriyle eşleşmemesi durumunda oluşur. Bu genellikle bir toplantı sonlandırılıp aynı meetingID ile yeniden oluşturulduğunda, ancak katılma URL'sinin hâlâ eski createTime değerini içermesi durumunda olur.