Implementation Recipes

This page lists the typical scenarios for connecting your website or app users with voice and video, along with how you can implement each scenario using the Gruveo Embed API and mobile SDKs.

Recipe #1: Connecting Scheduled Calls on a Marketplace-Type Website

This scenario is typical for websites that connect customers with service providers (e.g. students with teachers, patients with doctors etc.) The arrangement is as follows:

1. A customer (e.g. a student) books a call with a service provider (e.g. a teacher) on your Learning Connect website at https://www.learningconnect.com.
2. Behind the scenes, your website generates a one-time random Gruveo room name for the call, i.e. tyvqxln2uw4b.
3. The student and the teacher are both emailed the booking confirmation with the following link to join the call: https://www.learningconnect.com/video-call?room=tyvqxln2uw4b.
4. On the set date and time, the student and the teacher click the link and end up on a page of your website where a video call is established in the Gruveo widget.

The first step in implementing this scenario is to place the Gruveo embed on a page on your website, and then add the JavaScript code to make the embed automatically join the Gruveo room passed in the page's URL. Here is how to do it:

1. Create a page on your website (e.g. https://www.learningconnect.com/video-call) that will hold the Gruveo embed.
2. Embed a Gruveo widget on that page using  the JavaScript embedding method.
3. Assuming that you will be passing the Gruveo room name in the room GET parameter (so the URL emailed to the users will be https://www.learningconnect.com/video-call?room=tyvqxln2uw4b), implement a way to pass the value of the parameter to the JavaScript code you have running on the page. It could be passing the parameter value from your server side, or parsing the URL query string with JavaScript directly on the page.
4. In the event handler for the Gruveo embed's ready event, make the embed start the call automatically as follows:
   
   JavaScript

   embed.on("ready", function(e) { // Start a video call once the Gruveo widget has loaded. // The below assumes that the "room" variable contains // the room name to join. embed.call(room, true); });

   1 2 3 4 5 6

   embed.on("ready", function(e) {   // Start a video call once the Gruveo widget has loaded.   // The below assumes that the "room" variable contains   // the room name to join.   embed.call(room, true); });

5. Test your implementation by opening the https://www.learningconnect.com/video-call?room=tyvqxln2uw4b URL in two tabs of your browser. You should get connected with yourself in the Gruveo embed.

The final step is to implement the generation of the random Gruveo room name when a call is booked on your website. This is as simple as generating a random alphanumeric string of sufficient length (12 characters or more is recommended). You do not need to "register" or "create" the room with Gruveo beforehand as the rooms come into existence automatically when someone joins them. Randomizing the room name provides a sufficient degree of protection from unwanted users joining the call by pure chance.

Instead of passing the Gruveo room name in the URL, you may be passing the booking ID instead and then pulling the room name for the booking from the database, or fetching the booking's room name in some other way. This scenario can also be extended to connecting your users in a custom iOS or Android app using Gruveo's mobile SDKs.

Recipe #2: Letting Your App Users Call Each Other

In this advanced scenario, your app users can call each other directly. Behind the scenes, your app generates a random Gruveo room name for each call to connect the users. Here is how it works:

1. Alice taps a button in your app to call Bob.
2. A "Calling Bob..." screen is shown to Alice.
3. The app generates a random room name for the conversation, e.g. using the generateRandomCode() helper function in the Android SDK.
4. The app passes a message about an incoming call, along with the generated room name, to Bob.
5. An "Incoming call from Alice" screen is shown to Bob.
6. Assuming that Bob answers the call, the app launches a Gruveo call screen for him and passes the room name to the screen.
7. The app also passes a message to Alice notifying her instance of the app that Bob answered.
8. On Alice's end, the app launches a Gruveo call screen with the same room name.
9. Alice and Bob end up in the same Gruveo room and the call is established.

Note that in this scenario, the necessary signaling (i.e. the exchange of messages between the users' app instances) is left to your implementation.