-
Notifications
You must be signed in to change notification settings - Fork 85
/
README.html
60 lines (57 loc) · 4.86 KB
/
README.html
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
<!DOCTYPE html>
<html>
<head>
<title>Extensions-Hello-World</title>
</head>
<body>
<h1 id="extensions-hello-world">Extensions-Hello-World</h1>
<p>The Simplest Extension in the (Hello) World.</p>
<h2 id="motivation">Motivation</h2>
<p>The Hello World sample is designed to get you started building a Twitch Extension quickly. It contains all the key parts of a functioning Extension and can be immediately run in the <a href="https://github.com/twitchdev/developer-rig">Developer Rig</a>. For a fast guide to get started, visit the Developer Rig documentation.</p>
<h2 id="whats-in-the-sample">What's in the Sample</h2>
<p>The Hello World Extension provides a simple scenario that demonstrates the end-to-end flow of an Extension. On the frontend, a user clicks a button that can change the color of a circle. Instead of changing the CSS locally, it calls its Extension Backend Service (EBS) to update the color of the circle. That message is then sent via Twitch PubSub to update all clients listening to the PubSub topic.</p>
<p><strong>The sample is broken into two main components:</strong></p>
<ol>
<li>The Frontend of the Extension, comprised of HTML files for the different extension views and corresponding Javascript files and CSS. The frontend has the following functionality:
<ul>
<li>A button and script that makes a POST call to the EBS to request a color change for the circle</li>
<li>A GET call when the Extension is initialized to change the circle to the current color stored on the EBS</li>
<li>A listener to Twitch PubSub, that receives color change updates and then updates the circle color</li>
</ul>
</li>
<li>A lightweight EBS that performs the following functionality:
<ul>
<li>Spins up a simple HTTPS server with a POST handler for changing color</li>
<li>Validates an Extension JWT</li>
<li>Sends a new color message via Twitch PubSub for a specific channel</li>
</ul>
</li>
</ol>
<h2 id="using-the-sample">Using the Sample</h2>
<p>The recommended path to using this sample is with the <a href="https://github.com/twitchdev/developer-rig">Developer Rig</a>. Use the Developer Rig's <code>extension-init</code> command to clone this repository.</p>
<p>The Developer Rig is able to host the frontend Hello World files, but the EBS must be run and hosted separately.</p>
<h3 id="setting-up-your-backend-certificates">Setting Up Your Backend Certificates</h3>
<p>Twitch Extensions require SSL (TLS).</p>
<p>If you're using the Developer Rig and used it to create this extension, it will have already configured the certificates. Otherwise, you'll need to set up a certificate for local development. This will generate a new certificate (<code>server.crt</code> and <code>server.key</code>) for you and place it in the <code>conf/</code> directory. This certificate is different from the one used for the Developer Rig.</p>
<h4 id="on-macos">On MacOS</h4>
<p>Navigate to the root of the Hello World extension folder and run <code>npm install</code> and then <code>npm run cert</code></p>
<h4 id="on-windows">On Windows</h4>
<p>Run the following commands to generate the necessary certificates for your Hello World backend</p>
<ol>
<li><code>node scripts/ssl.js</code></li>
<li><code>mkdir ../my-extension/conf</code></li>
<li><code>mv ssl/selfsigned.crt ../my-extension/conf/server.crt</code></li>
<li><code>mv ssl/selfsigned.key ../my-extension/conf/server.key</code></li>
</ol>
<h3 id="running-hello-world">Running Hello World</h3>
<p>If you're using the Developer Rig, it has buttons in its UI to perform the following actions.</p>
<p>To run the EBS, run <code>node services/backend</code>, with the following command line arguments: <code>-c <client id></code>, <code>-s <secret></code>, <code>-o <owner id></code>.</p>
<p>This provides the EBS with your Extension client ID, Extension secret and the user ID of the Extension owner (likely you). These are necessary to validate calls to your EBS and make calls to Twitch services such as PubSub.</p>
<p>If you do not want to pass in command line arguments, you can also directly set the following environment variables: <code>EXT_SECRET</code>, <code>EXT_CLIENT_ID</code>, <code>EXT_OWNER_ID</code> in your code.</p>
<p>You can get your client ID and secret from your <a href="https://dev.twitch.tv/dashboard/extensions">Extension Dashboard</a>.</p>
<p>To get the owner ID, you will need to execute a simple CURL command against the Twitch <code>/users</code> endpoint. You'll need your extension client ID as part of the query (this will be made consistent with the Developer Rig shortly, by using <em>owner name</em>).</p>
<pre><code class="language-bash">curl -H "Client-ID: <client id>" -X GET "https://api.twitch.tv/helix/users?login=<owner name>"
</code></pre>
<p><strong>Note -</strong> If you haven't yet created an extension, you can start that process <a href="https://dev.twitch.tv/extensions">here</a>.</p>
</body>
</html>