appearin.github.io/tutorial.html at master · katyaap/appearin.github.io · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
<html>

    <head>
        <link rel="stylesheet" href="css/styles.css">
    </head>

    <body>

        <div class="wrapper">
        <header class="main-header">
            <div class="logo">
                <img src="logo.svg" alt="">
                <p>appear.in</p>
            </div>
            <p class="back-link"><a href="https://appear.in">Back to appear.in</a></p>
        </header>


            <main>

        <h1 id="tutorial">Tutorial</h1>

        <section>
            <p>Hi and welcome to the first appear.in API tutorial. Here, we'll create a simple web application that creates and embeds an appear.in room directly on your site.</p>

            <p>If you are looking for is a simple embeddable version, this is something that we are working on, but is not ready for prime time just yet.</p>

            <p>The API is currently severely undocumented, but can assure you that proper documentation is underway. For now, we hope that this tutorial will provide you with the knowhow necessary to create applications using appear.in.</p>
        </section>


        <article>
            <header class="sticky">
                <h2 id="requirements">Requirements</h2>
            </header>

            <section>
                <p>In addition to our JavaScript library, we require you to include jQuery for the <code>postMessage</code> API to perform like require it to. We are looking into ways making this optional.</p>
            </section>

        </article>

        <article>
            <header class="sticky">
                <h2 id="checkforappearincompatibility">Check for appear.in compatibility</h2>
            </header>
            <section>
                <p>The first thing we will have to do is to check if the client browser supports the technologies that is needed for appear.in to work properly. While appear.in itself will display an error message when a non-supported browser is detected, you might want to do this on your site instead to improve user experience. We have created a simple JavaScript library that you can use on your site. This library is loaded by including the following line <em>after</em> including jQuery.</p>

        <pre><code>&lt;script src="http://iswebrtcready.appear.in/apiv2.js"&gt;&lt;/script&gt;
        </code></pre>

        <p>This lets you run our test battery by running the <code>API.isApperinCompatible()</code> method.</p>

        <pre><code>API.isAppearinCompatible(function (data) {
            // the call was successful
            window.console.log(data);
        }, function (error) {
            // the call was unsuccessful
            window.console.log(error);
        })
        </code></pre>

                <p>This will run all the tests available in our test battery (1) and return a <code>true</code> or <code>false</code> boolean, as well as an array containing the result of all the tests that has been run. Refer to the output of the <code>window.console.log(data)</code> for the complete content until the API documentation is finished.</p>

                <h3 id="technicaldeets">Technical deets</h3>

                <p>The tests are run by embedding a minimal iframed version of the <a href="http://iswebrtcready.appear.in">iswebrtcready.appear.in</a> test web site which will run all of our tests and report the results back to your site. We plan to package these test for you to put on your site without the need for embedding our tests.</p>

                <h3 id="caveats">Caveats</h3>

                <p>While we will keep the <code>apiv2.js</code> file and its syntax and methods available for the foreseeable future and we will try to let you know of any changes you should know about using <code>console.log</code> messages. That being said, this is a very early and experimental version of the API and the final version <em>will be changed</em>. A new API JavaScript library will be provided as soon as we feel it to be ready. <a href="http://eepurl.com/J-_Qr">Sign up to our mailing list</a> to be notified when this happens.</p>

            </section>
        </article>

        <article>
            <header class="sticky">
                <h2 id="createtheroom">Create the room</h2>
            </header>

            <section>

                <p>After making sure that the client browser support appear.in, we will go on to create a room that you can use. Our API does not yet expose the ability to create rooms programatically (2), so for now we'll have to exploit the ability of appear.in to create a room from any given string. By creating a sufficiently long randomly generated string, this will give us a statistical "guarantee" that the room is unoccupied. The longer the string, the smaller the chance of creating a room that is already occupied. We'll create a room name with thirty alphanumeric characters, which will give us 36<sup>30</sup>, or a few tredecillions shy of 49 quattuordecillion, possible character combinations.</p>

<pre><code>var randomRoomNameGenerator = function () {
    // predefine the alphabet used.
    var alphabet = 'qwertyuiopasdfghjklzxcvbnm1234567890';

    // set the length of the room name
    var roomNameLength = 30;

    // initialize the room name as an empty string
    var roomName = '';

    // repeat this 30 times
    for (var i=0; i&lt;roomNameLength; i++) {
        // get a random character from the alphabet
        var character = alphabet[Math.round(Math.random()*(alphabet.length-1))];

        // add the character to the roomName
        roomName = roomName + character;
    }

    // pre- and append appear.in URL elements
    roomName = 'https://appear.in/' + roomName + '?lite';

    // return the result
    return roomName;
}
</code></pre>

        <p>This method will return a valid roomname, ready to be inserted into an anchor tag or even an iframe.</p>
        </section>
        </article>

        <article>
            <header class="sticky">
                <h2 id="embedappearin">Embed appear.in</h2>
            </header>
            <section>

                <p>Appear.in rooms are possible to embed inside ordinary iframes, making it possible to create entire video based services using appear.in rooms as their base. To do this we'll simply set the iframe <code>src</code> attribute to the generated room name.</p>

<pre><code>&lt;html&gt;
    &lt;body&gt;
        &lt;h1&gt;My awesome service&lt;/h1&gt;
        &lt;button onclick="createRoom()"&gt;Create room&lt;/button&gt;

        &lt;iframe id="appearin-room"&gt;

        &lt;script&gt;
            // create the room on button press
            window.createRoom = function () {
                // setting a room name. Pair this with the random room generator code above for real power
                var roomName = 'this-is-a-room';
                roomName = 'https://appear.in/' + roomName + '?lite';

                // set the iframe source to load the room
                var iframe = document.getElementById('appearin-room')
                iframe.setAttribute('src', roomName);
            }
        &lt;/script&gt;
    &lt;/body&gt;
&lt;/html&gt;
</code></pre>


                <h3 id="userexperience">User experience</h3>

                <p>Browsers will display a camera access request dialog the first time a web site requests access to it, but seeing as the camera access dialog comes from the appear.in domain, this means that if the user has ever allowed camera access to appear.in the camera and microphone will automatically turn on when the iframe has loaded. However, we have implemented a user consent dialogue to prevent users from automatically broadcasting their face without their expressed consent.</p>
            </section>
        </article>


        <article>
            <header class="sticky">
                <h2 id="completecode">Complete code</h2>
            </header>

        <section>

<pre><code>&lt;html&gt;
    &lt;body&gt;
        &lt;h1&gt;My awesome service&lt;/h1&gt;
        &lt;p&gt;Is appear.in compatible? &lt;span id="compatability-test-result"&gt;Maybe&lt;/span&gt;&lt;/p&gt;
        &lt;button id="create-room-button"&gt;Create room&lt;/button&gt;

        &lt;iframe id="appearin-room"&gt;&lt;/iframe&gt;


        &lt;script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"&gt;&lt;/script&gt;
        &lt;script src="http://iswebrtcready.appear.in/apiv2.js"&gt;&lt;/script&gt;

        &lt;script&gt;
            document.getElementById('create-room-button').onclick = function () {
                // create the room on button press
                    var randomRoomNameGenerator = function () {
                        // predefine the alphabet used.
                        var alphabet = 'qwertyuiopasdfghjklzxcvbnm1234567890';

                        // set the length of the room name
                        var roomNameLength = 30;

                        // initialize the room name as an empty string
                        var roomName = '';

                        // repeat this 30 times
                        for (var i=0; i&lt;roomNameLength; i++) {
                            // get a random character from the alphabet
                            var character = alphabet[Math.round(Math.random()*(alphabet.length-1))];

                            // add the character to the roomName
                            roomName = roomName + character;
                        }

                        // pre- and append appear.in URL elements
                        roomName = 'https://appear.in/' + roomName + '?lite';

                        // return the result
                        return roomName;
                    }

                    // setting a room name. Pair this with the random room generator code above for real power
                    var roomName = randomRoomNameGenerator();

                    // set the iframe source to load the room
                    var iframe = document.getElementById('appearin-room');
                    iframe.setAttribute('src', roomName);
            }

            API.isAppearinCompatible(function (data) {
                if (data.isSupported) {
                    document.getElementById('compatability-test-result').innerHTML = 'Yes';
                }
                else {
                    document.getElementById('compatability-test-result').innerHTML = 'No';
                }
            });
        &lt;/script&gt;

    &lt;/body&gt;
&lt;/html&gt;
</code></pre>
        </section>
        </article>


        <article>
            <header class="sticky">
                <h2 id="footnotes">Footnotes</h2>
            </header>

            <section>
                <p>(1) We are working on making it possible to run single test on your site if you so wish, as well as list all the tests available. Soon, very soon.</p>
                <p>(2) We are planning to expand our API to be able to create shorter, mnemonic rooms guaranteed to be unique and unoccupied, but this is not implemented just yet.</p>
            </section>
        </article>

        </main>

        <footer>
            <a href="https://appear.in">Appear.in</a>
        </footer>
        </div>
    </body>
</html>