API sürümü: 4.x en güncel 3.x

BigBlueButton 3.x için API dokümantasyonunu görüntülüyorsunuz. Güncel sürüm: BigBlueButton 4.x. Yükseltme mi planlıyorsunuz? Geçiş kılavuzu, API çağrılarınızda yapmanız gereken tüm değişiklikleri listeler.

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ı, doğrudan son kullanıcının tarayıcısında (yönlendirme URL'si olarak) çağrılan, sağlama toplamıyla korunan tek API uç noktasıdır. Sağlama toplamıyla korunan 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 2.4+

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.
webVoiceConf String Kullanımdan kaldırıldı Removed in 4.0 Eski Flash istemcisi için özel ses dahili numarası. Değer değerlendirilmez ve hiçbir etkisi yoktur.

İ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.
auth Boolean (koşullu) ‎⚠ Belgelenmemiş Kullanıcıyı kimliği doğrulanmış olarak işaretleyin. Koşullu mantık: guest belirtilmemişse auth varsayılan olarak true değerini alır. guest belirtilmişse (false dahil herhangi bir değerle), auth açıkça ayarlanmadığı sürece varsayılan olarak false değerini alır.
defaultLayout String — ‎⚠ Belgelenmemiş BBB 3.0 sürümünde resmî API'den kaldırılmıştır. Sunucu değeri hâlâ kabul eder ancak hiçbir zaman değerlendirmez; dolayısıyla hiçbir etkisi yoktur. İstemcinin başlangıç düzenini ayarlamak için userdata-bbb_default_layout kullanın.
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.

Sunucu tarafındaki getJoinUrlUserdataBlocklist engelleme listesi yalnızca getJoinUrl aracılığıyla oluşturulan katılım URL'leri için geçerlidir. join çağrısının kendisi tüm userdata anahtarlarını kabul eder.

userdata- sonrasındaki bölüm başka bir kısa çizgi içermemelidir; aksi takdirde parametre kaldırılır. userdata-bbb_ öneki BigBlueButton için ayrılmıştır; entegrasyon verileri için kendi önekinizi kullanın (ör. userdata-myapp_cohort). Tam liste İstemci Ayarları bölümünde mevcuttur.

Ö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>
  <guestStatus>ALLOW</guestStatus>
  <url>https://api-guide.bbbserver.com/html5client/?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, bbbserver.de web arayüzündeki odalar veya davet bağlantıları üzerinden katılan katılımcıların katılım URL'leri otomatik olarak oluşturulur. Integration API kullanıyorsanız join çağrısını yukarıda açıklandığı gibi kendiniz oluşturun.

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.