Setiap solusi konferensi
yang Anda tentukan dalam
manifes
project skrip memiliki onCreateFunction
terkait. Add-on memanggil fungsi ini untuk membuat konferensi setiap kali pengguna mencoba memilih sebuah peristiwa terkait solusi konferensi tersebut.
Anda harus mengimplementasikan setiap onCreateFunction
yang dijelaskan dalam manifes add-on.
Secara umum, fungsi ini harus melakukan hal berikut:
- Mengambil informasi acara Google Kalender apa pun, seperti ID acara atau daftar tamu, yang mungkin diperlukan sistem konferensi pihak ketiga untuk membuat konferensi.
- Hubungkan ke layanan konferensi pihak ketiga dan buat konferensi baru menggunakan informasi acara Google Kalender.
- Jika permintaan pembuatan konferensi gagal karena alasan tertentu, gunakan informasi
error untuk membuat dan menampilkan
objek
ConferenceData
yang berisiConferenceError
. Jika tidak, selesaikan langkah berikutnya.- Lakukan inisialisasi sinkronisasi konferensi.
- Gunakan informasi yang ditampilkan oleh layanan konferensi pihak ketiga untuk
mem-build dan menampilkan objek
ConferenceData
baru.
Mengambil informasi peristiwa
Untuk membuat konferensi pihak ketiga, diperlukan informasi tertentu tentang acara Google Kalender yang sesuai. Informasi persis peristiwa yang diperlukan bervariasi antara sistem konferensi pihak ketiga yang berbeda, tetapi sering kali mencakup waktu mulai, waktu berakhir, ringkasan, daftar peserta, dan ID acara.
Saat dipanggil, setiap onCreateFunction
yang Anda tentukan akan menerima argumen yang
berisi ID kalender dan acara. Anda dapat menggunakan ID ini untuk mengambil informasi lengkap acara menggunakan layanan lanjutan Google Kalender.
Google Kalender dapat menambahkan detail konferensi ke acara sebelum acara tersedia. Dalam kasus semacam itu, Google Kalender akan meneruskan onCreateFunction
eventId
yang valid, tetapi panggilan berikutnya ke Calendar.Events.get()
dapat menghasilkan
respons error yang menyatakan bahwa acara tersebut tidak ada. Dalam kasus ini, sebaiknya buat konferensi pihak ketiga menggunakan data placeholder. Data ini akan diganti saat peristiwa disinkronkan lagi.
Membuat konferensi pihak ketiga
Setelah mengambil data peristiwa yang diperlukan, onCreateFunction
harus
terhubung ke sistem konferensi pihak ketiga untuk membuat konferensi.
Biasanya, hal ini dilakukan dengan membuat permintaan API yang didukung oleh
sistem konferensi pihak ketiga. Periksa dokumentasi untuk solusi konferensi pihak ketiga Anda guna menentukan permintaan API yang dapat digunakan untuk membuat konferensi.
Di Apps Script, cara termudah untuk menangani pembuatan permintaan API eksternal adalah dengan menggunakan library open source OAuth2 for Apps Script atau OAuth1 for Apps Script. Anda juga dapat terhubung ke API eksternal menggunakan layanan UrlFetch, tetapi hal ini mengharuskan Anda menangani detail otorisasi secara eksplisit.
Setelah meminta pembuatan konferensi, Anda mungkin perlu membuat permintaan tambahan untuk mengambil detail konferensi baru.
Melakukan inisialisasi sinkronisasi konferensi
Setelah add-on berhasil membuat konferensi di sistem pihak ketiga, perlu beberapa langkah untuk mengaktifkan sinkronisasi agar perubahan pada acara Google Kalender dapat tercermin dalam konferensi tersebut.
Lihat Menyinkronkan perubahan Kalender untuk mengetahui detail cara menyiapkan sinkronisasi setelah pembuatan konferensi.
Membangun respons data konferensi
Dengan menggunakan informasi konferensi yang ditampilkan oleh layanan pihak ketiga,
onCreateFunction
kemudian harus membuat dan menampilkan
objek
ConferenceData
;
bagian Data konferensi
menjelaskan konten objek ini. Google Kalender menggunakan informasi tersebut untuk mengarahkan pengguna ke konferensi setelah konferensi dimulai.
Saat membuat objek ConferenceData
, perlu diketahui bahwa ada beberapa batasan terkait panjang kolom, format
URI titik entri, dan kombinasi titik entri yang diizinkan. Misalnya,
maksimal ada satu titik entri VIDEO
dalam satu
ConferenceData
. Batasan ini identik dengan batasan yang dijelaskan
di Peristiwa Calendar API untuk kolom
conferenceData
yang sesuai, meskipun tidak semua kolom peristiwa API yang dijelaskan di sana
tersedia di Apps Script.
Menangani error
Dalam beberapa kasus, pembuatan konferensi tidak dapat diselesaikan karena
terjadi error oleh sistem konferensi pihak ketiga. Dalam hal ini,
add-on Anda harus menangani kondisi error secara andal dengan membuat dan
menampilkan objek
ConferenceData
yang berisi
detail
ConferenceError
,
sehingga Google Kalender dapat bertindak dengan sesuai.
Saat membuat objek ConferenceData
untuk melaporkan error, Anda tidak
perlu menyertakan komponen ConferenceData
selain dari
objek ConferenceError
. ConferenceErrors
dapat memiliki ConferenceErrorType
, pesan error, dan jika terjadi autentikasi, URL yang memungkinkan pengguna login ke sistem konferensi pihak ketiga.
Contoh
Berikut ini contoh onCreateFunction
(perhatikan bahwa nama
fungsi dapat berupa apa saja; Anda hanya perlu menentukannya dalam manifes
project add-on).
Fungsi create3rdPartyConference()
menghubungi sistem pihak ketiga untuk membuat konferensi di sana, dan fungsi getAuthenticationUrl()
membuat URL autentikasi sistem pihak ketiga. Hal ini tidak diterapkan
sepenuhnya di sini karena sangat bergantung pada detail sistem pihak ketiga.
Fungsi initializeSyncing()
tidak ditampilkan di sini; fungsi ini menangani pekerjaan awal yang diperlukan untuk sinkronisasi.
Lihat Menyinkronkan perubahan kalender
untuk mengetahui detailnya.
/** * Creates a conference, then builds and returns a ConferenceData object * with the corresponding conference information. This method is called * when a user selects a conference solution defined by the add-on that * uses this function as its 'onCreateFunction' in the add-on manifest. * * @param {Object} arg The default argument passed to a 'onCreateFunction'; * it carries information about the Google Calendar event. * @return {ConferenceData} */ function createConference(arg) { const eventData = arg.eventData; const calendarId = eventData.calendarId; const eventId = eventData.eventId; // Retrieve the Calendar event information using the Calendar // Advanced service. var calendarEvent; try { calendarEvent = Calendar.Events.get(calendarId, eventId); } catch (err) { // The calendar event does not exist just yet; just proceed with the // given event ID and allow the event details to sync later. console.log(err); calendarEvent = { id: eventId, }; } // Create a conference on the third-party service and return the // conference data or errors in a custom JSON object. var conferenceInfo = create3rdPartyConference(calendarEvent); // Build and return a ConferenceData object, either with conference or // error information. var dataBuilder = ConferenceDataService.newConferenceDataBuilder(); if (!conferenceInfo.error) { // No error, so build the ConferenceData object from the // returned conference info. var phoneEntryPoint = ConferenceDataService.newEntryPoint() .setEntryPointType(ConferenceDataService.EntryPointType.PHONE) .setUri('tel:+' + conferenceInfo.phoneNumber) .setPin(conferenceInfo.phonePin); var adminEmailParameter = ConferenceDataService.newConferenceParameter() .setKey('adminEmail') .setValue(conferenceInfo.adminEmail); dataBuilder.setConferenceId(conferenceInfo.id) .addEntryPoint(phoneEntryPoint) .addConferenceParameter(adminEmailParameter) .setNotes(conferenceInfo.conferenceLegalNotice); if (conferenceInfo.videoUri) { var videoEntryPoint = ConferenceDataService.newEntryPoint() .setEntryPointType(ConferenceDataService.EntryPointType.VIDEO) .setUri(conferenceInfo.videoUri) .setPasscode(conferenceInfo.videoPasscode); dataBuilder.addEntryPoint(videoEntryPoint); } // Since the conference creation request succeeded, make sure that // syncing has been enabled. initializeSyncing(calendarId, eventId, conferenceInfo.id); } else if (conferenceInfo.error === 'AUTH') { // Authenentication error. Implement a function to build the correct // authenication URL for the third-party conferencing system. var authenticationUrl = getAuthenticationUrl(); var error = ConferenceDataService.newConferenceError() .setConferenceErrorType( ConferenceDataService.ConferenceErrorType.AUTHENTICATION) .setAuthenticationUrl(authenticationUrl); dataBuilder.setError(error); } else { // Other error type; var error = ConferenceDataService.newConferenceError() .setConferenceErrorType( ConferenceDataService.ConferenceErrorType.TEMPORARY); dataBuilder.setError(error); } // Don't forget to build the ConferenceData object. return dataBuilder.build(); } /** * Contact the third-party conferencing system to create a conference there, * using the provided calendar event information. Collects and retuns the * conference data returned by the third-party system in a custom JSON object * with the following fields: * * data.adminEmail - the conference administrator's email * data.conferenceLegalNotice - the conference legal notice text * data.error - Only present if there was an error during * conference creation. Equal to 'AUTH' if the add-on user needs to * authorize on the third-party system. * data.id - the conference ID * data.phoneNumber - the conference phone entry point phone number * data.phonePin - the conference phone entry point PIN * data.videoPasscode - the conference video entry point passcode * data.videoUri - the conference video entry point URI * * The above fields are specific to this example; which conference information * your add-on needs is dependent on the third-party conferencing system * requirements. * * @param {Object} calendarEvent A Calendar Event resource object returned by * the Google Calendar API. * @return {Object} */ function create3rdPartyConference(calendarEvent) { var data = {}; // Implementation details dependent on the third-party system API. // Typically one or more API calls are made to create the conference and // acquire its relevant data, which is then put in to the returned JSON // object. return data; } /** * Return the URL used to authenticate the user with the third-party * conferencing system. * * @return {String} */ function getAuthenticationUrl() { var url; // Implementation details dependent on the third-party system. return url; }