# Client-Messaging-SDK für IVS Chat: Tutorial für JavaScript, Teil 1: Chaträume
Hierbei handelt es sich um den ersten Teil eines zweiteiligen Tutorials. Darin lernen Sie die Grundlagen der Arbeit mit dem Amazon IVS Chat Client Messaging JavaScript SDK kennen, indem Sie eine voll funktionsfähige App mit JavaScript/TypeScript entwickeln. Wir nennen die App *Chatterbox*.
Die Zielgruppe sind erfahrene Entwickler, die das Amazon IVS Chat Messaging SDK noch nicht kennen. Sie sollten mit der Programmiersprache JavaScript/TypeScript und der Bibliothek React vertraut sein.
Der Kürze halber bezeichnen wir das Amazon IVS Chat Client Messaging JavaScript SDK als Chat JS SDK.
**Hinweis**: In einigen Fällen sind die Codebeispiele für JavaScript und TypeScript identisch, daher werden sie kombiniert.
Der vorliegende erste Teil des Tutorials ist in mehrere Abschnitte unterteilt:
1. [Einrichten eines lokalen Authentifizierungs-/Autorisierungsservers](#chat-js-rooms-auth-server)
1. [Erstellen eines Chatterbox-Projekts](#chat-js-rooms-chatterbox)
1. [Verbinden mit einem Chatroom](#chat-js-rooms-connect)
1. [Erstellen eines Token-Anbieters](#chat-js-rooms-token-provider)
1. [Beobachten von Verbindungsaktualisierungen](#chat-js-rooms-connection-state)
1. [Erstellen einer Schaltflächenkomponente zum Senden](#chat-js-rooms-send-button)
1. [Erstellen einer Nachrichteneingabe](#chat-js-rooms-message-input)
1. [Nächste Schritte](#chat-js-rooms-next-steps)
Umfassende Informationen zum SDK finden Sie im [Amazon IVS Chat Client Messaging SDK](chat-sdk.md) (im vorliegenden *Benutzerhandbuch zu Amazon IVS Chat*) und unter [Chat Client Messaging: SDK for JavaScript Reference](https://aws.github.io/amazon-ivs-chat-messaging-sdk-js/latest/) (Chat Client Messaging: SDK für JavaScript – Referenz) auf GitHub.
## Voraussetzungen
+ Sie sollten mit JavaScript/TypeScript und der Bibliothek React vertraut sein. Wenn Sie mit React nicht vertraut sind, können Sie unter [Einführung in Tic-Tac-Toe](https://react.dev/learn/tutorial-tic-tac-toe) die Grundlagen kennenlernen.
+ Lesen Sie sich [Erste Schritte mit Amazon IVS Chat](getting-started-chat.md) durch.
+ Erstellen Sie einen AWS-IAM-Benutzer mit den Fähigkeiten CreateChatToken und CreateRoom, die in einer vorhandenen IAM-Richtlinie definiert sind. (Siehe ). [Erste Schritte mit Amazon IVS Chat](getting-started-chat.md).)
+ Stellen Sie sicher, dass die Geheim-/Zugriffsschlüssel für diesen Benutzer in einer Datei mit den AWS-Anmeldeinformationen gespeichert sind. Entsprechende Anweisungen finden Sie im [Benutzerhandbuch zur AWS-CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) (insbesondere unter [Einstellungen für Konfigurations- und Anmeldeinformationsdateien](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)).
+ Erstellen Sie einen Chatroom und speichern Sie dessen ARN. Siehe [Erste Schritte mit Amazon IVS Chat](getting-started-chat.md). (Wenn Sie den ARN nicht speichern, können Sie ihn später über die Konsole oder die Chat-API nachschlagen.)
+ Installieren Sie die Umgebung Node.js 14\$1 mit dem Paketmanager NPM oder Yarn.
## Einrichten eines lokalen Authentifizierungs-/Autorisierungsservers
Die Erstellung von Chatrooms und die Generierung der Chat-Token, die benötigt werden, damit das Chat JS SDK die Clients für Ihre Chatrooms authentifizieren und autorisieren kann, erfolgt in Ihrer Backend-Anwendung. Sie müssen Ihr eigenes Backend verwenden, da die AWS-Schlüssel nicht sicher in einer mobilen App gespeichert werden können. Versierte Angreifer könnten diese extrahieren und Zugriff auf Ihr AWS-Konto erlangen.
Weitere Informationen finden Sie unter [Erstellen eines Chat-Tokens](getting-started-chat-auth.md) unter *Erste Schritte mit Amazon IVS Chat*. Wie im dortigen Flussdiagramm gezeigt, erfolgt die Erstellung eines Chat-Tokens in Ihrer serverseitigen Anwendung. Das bedeutet, dass Ihre App eigene Mittel zur Generierung eines Chat-Tokens bereitstellen muss, indem sie ein Token von der serverseitigen Anwendung anfordert.
In diesem Abschnitt werden die Grundlagen der Erstellung eines Token-Anbieters in Ihrem Backend vermittelt. Mit dem Express-Framework erstellen wir einen lokalen Live-Server, der die Erstellung von Chat-Token mithilfe Ihrer lokalen AWS-Umgebung verwaltet.
Erstellen Sie ein leeres `npm`-Projekt mit NPM. Erstellen Sie ein Verzeichnis für Ihre Anwendung und machen Sie dieses zu Ihrem Arbeitsverzeichnis:
```
$ mkdir backend & cd backend
```
Erstellen Sie mit `npm init` eine `package.json`-Datei für die Anwendung:
```
$ npm init
```
Durch diesen Befehl werden Sie aufgefordert, unter anderem den Namen und die Version der Anwendung einzugeben. Drücken Sie vorerst einfach **RETURN**, um die Standardwerte zu akzeptieren, mit der folgenden Ausnahme:
```
entry point: (index.js)
```
Drücken Sie **RETURN**, um den vorgeschlagenen Standarddateinamen `index.js` zu akzeptieren, oder geben Sie den gewünschten Namen für die Hauptdatei ein.
Installieren Sie nun die erforderlichen Abhängigkeiten:
```
$ npm install express aws-sdk cors dotenv
```
`aws-sdk` erfordert Variablen der Konfigurationsumgebung, die automatisch aus einer Datei namens `.env` im Stammverzeichnis geladen werden. Um sie zu konfigurieren, erstellen Sie eine neue Datei mit dem Namen `.env` und tragen Sie die fehlenden Konfigurationsinformationen ein:
```
# .env
# The region to send service requests to.
AWS_REGION=us-west-2
# Access keys use an access key ID and secret access key
# that you use to sign programmatic requests to AWS.
# AWS access key ID.
AWS_ACCESS_KEY_ID=...
# AWS secret access key.
AWS_SECRET_ACCESS_KEY=...
```
Jetzt erstellen wir im Stammverzeichnis eine Eintrittspunktdatei mit dem Namen, den Sie oben im Befehl `npm init` eingegeben haben. In diesem Fall verwenden wir `index.js` und importieren alle erforderlichen Pakete:
```
// index.js
import express from 'express';
import AWS from 'aws-sdk';
import 'dotenv/config';
import cors from 'cors';
```
Erstellen Sie jetzt eine neue Instance von `express`:
```
const app = express();
const port = 3000;
app.use(express.json());
app.use(cors({ origin: ['http://127.0.0.1:5173'] }));
```
Danach können Sie die erste Endpunkt-POST-Methode für den Token-Anbieter erstellen. Entnehmen Sie die erforderlichen Parameter dem Hauptteil der Anforderung (`roomId`, `userId`, `capabilities` und`sessionDurationInMinutes`):
```
app.post('/create_chat_token', (req, res) => {
const { roomIdentifier, userId, capabilities, sessionDurationInMinutes } = req.body || {};
});
```
Fügen Sie die Validierung der erforderlichen Felder hinzu:
```
app.post('/create_chat_token', (req, res) => {
const { roomIdentifier, userId, capabilities, sessionDurationInMinutes } = req.body || {};
if (!roomIdentifier || !userId) {
res.status(400).json({ error: 'Missing parameters: `roomIdentifier`, `userId`' });
return;
}
});
```
Nach der Vorbereitung der POST-Methode integrieren wir `createChatToken` mit `aws-sdk` für die Kernfunktionalität der Authentifizierung/Autorisierung:
```
app.post('/create_chat_token', (req, res) => {
const { roomIdentifier, userId, capabilities, sessionDurationInMinutes } = req.body || {};
if (!roomIdentifier || !userId || !capabilities) {
res.status(400).json({ error: 'Missing parameters: `roomIdentifier`, `userId`, `capabilities`' });
return;
}
ivsChat.createChatToken({ roomIdentifier, userId, capabilities, sessionDurationInMinutes }, (error, data) => {
if (error) {
console.log(error);
res.status(500).send(error.code);
} else if (data.token) {
const { token, sessionExpirationTime, tokenExpirationTime } = data;
console.log(`Retrieved Chat Token: ${JSON.stringify(data, null, 2)}`);
res.json({ token, sessionExpirationTime, tokenExpirationTime });
}
});
});
```
Fügen Sie am Ende der Datei einen Port-Listener für die App `express` hinzu:
```
app.listen(port, () => {
console.log(`Backend listening on port ${port}`);
});
```
Nun können Sie den Server mit dem folgenden Befehl im Stammverzeichnis des Projekts ausführen:
```
$ node index.js
```
**Tipp**: Dieser Server akzeptiert URL-Anforderungen unter https://localhost:3000.
## Erstellen eines Chatterbox-Projekts
Zunächst erstellen Sie das React-Projekt namens `chatterbox`. Führen Sie diesen Befehl aus:
```
npx create-react-app chatterbox
```
Sie können das Chat Client Messaging JS SDK über den [Node Package Manager](https://www.npmjs.com/) (NPM) oder den [Paketmanager Yarn](https://yarnpkg.com/) integrieren:
+ NPM: `npm install amazon-ivs-chat-messaging`
+ Yarn: `yarn add amazon-ivs-chat-messaging`
## Verbinden mit einem Chatroom
Hier erstellen Sie einen `ChatRoom` und stellen mit asynchronen Methoden eine Verbindung dazu her. Die Klasse `ChatRoom` verwaltet die Verbindung der Benutzer zum Chat JS SDK. Um eine Verbindung zu einem Chatroom herzustellen, müssen Sie eine Instance von `ChatToken` in Ihrer React-Anwendung angeben.
Navigieren Sie zur `App`-Datei, die im `chatterbox`-Standardprojekt erstellt wurde, und löschen Sie alles zwischen den beiden `
`-Tags. Von dem vorab eingetragenen Code wird nichts benötigt. An dieser Stelle ist unsere `App` ziemlich leer.
```
// App.jsx / App.tsx
import * as React from 'react';
export default function App() {
return
Hello!
;
}
```
Erstellen Sie eine neue `ChatRoom`-Instance und übergeben Sie sie mit dem Hook `useState` an den Status. Das erfordert die Übergabe von `regionOrUrl` (die AWS-Region, in der der Chatroom gehostet wird) und `tokenProvider` (wird für den Authentifizierungs- und Autorisierungsablauf im Backend verwendet, der in nachfolgenden Schritten erstellt wird).
**Wichtig**: Sie müssen dieselbe AWS-Region verwenden, in der Sie den Chatroom unter [Erste Schritte mit Amazon IVS Chat](getting-started-chat-create-room.md) erstellt haben. Die API ist ein regionaler AWS-Service. Eine Liste der unterstützten Regionen und HTTPS-Service-Endpunkte für Amazon IVS Chat finden Sie auf der Seite [Regionen für Amazon IVS Chat](https://docs.aws.amazon.com/general/latest/gr/ivs.html#ivs_region).
```
// App.jsx / App.tsx
import React, { useState } from 'react';
import { ChatRoom } from 'amazon-ivs-chat-messaging';
export default function App() {
const [room] = useState(() =>
new ChatRoom({
regionOrUrl: process.env.REGION as string,
tokenProvider: () => {},
}),
);
return
Hello!
;
}
```
## Erstellen eines Token-Anbieters
Als nächsten Schritt müssen wir eine parameterlose `tokenProvider`-Funktion erstellen, die vom `ChatRoom`-Konstruktor benötigt wird. Zunächst erstellen wir eine `fetchChatToken`-Funktion, die eine POST-Anforderung an die Backend-Anwendung übermittelt, die Sie unter [Einrichten eines lokalen Authentifizierungs-/Autorisierungsservers](#chat-js-rooms-auth-server) eingerichtet haben. Chat-Token enthalten die notwendigen Informationen, damit das SDK erfolgreich eine Verbindung zum Chatroom herstellen kann. Die Chat-API nutzt diese Token als sichere Methode, um die Identität von Benutzern, die Fähigkeiten innerhalb eines Chatrooms und die Sitzungsdauer zu validieren.
Erstellen Sie im Projektnavigator eine neue TypeScript/JavaScript-Datei mit dem Namen `fetchChatToken`. Erstellen Sie eine Abrufanforderung an die `backend`-Anwendung und geben Sie das Objekt `ChatToken` aus der Antwort zurück. Fügen Sie die Eigenschaften des Anforderungshauptteils hinzu, die für die Erstellung eines Chat-Tokens erforderlich sind. Verwenden Sie die für [Amazon-Ressourcennamen (ARNs)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) definierten Regeln. Diese Eigenschaften sind im Vorgang [CreateChatToken](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/API_CreateChatToken.html#API_CreateChatToken_RequestBody) dokumentiert.
**Hinweis**: Die hier verwendete URL ist dieselbe URL, die Ihr lokaler Server beim Ausführen der Backend-Anwendung erstellt hat.
------
#### [ TypeScript ]
```
// fetchChatToken.ts
import { ChatToken } from 'amazon-ivs-chat-messaging';
type UserCapability = 'DELETE_MESSAGE' | 'DISCONNECT_USER' | 'SEND_MESSAGE';
export async function fetchChatToken(
userId: string,
capabilities: UserCapability[] = [],
attributes?: Record,
sessionDurationInMinutes?: number,
): Promise {
const response = await fetch(`${process.env.BACKEND_BASE_URL}/create_chat_token`, {
method: 'POST',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
userId,
roomIdentifier: process.env.ROOM_ID,
capabilities,
sessionDurationInMinutes,
attributes
}),
});
const token = await response.json();
return {
...token,
sessionExpirationTime: new Date(token.sessionExpirationTime),
tokenExpirationTime: new Date(token.tokenExpirationTime),
};
}
```
------
#### [ JavaScript ]
```
// fetchChatToken.js
export async function fetchChatToken(
userId,
capabilities = [],
attributes,
sessionDurationInMinutes) {
const response = await fetch(`${process.env.BACKEND_BASE_URL}/create_chat_token`, {
method: 'POST',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
userId,
roomIdentifier: process.env.ROOM_ID,
capabilities,
sessionDurationInMinutes,
attributes
}),
});
const token = await response.json();
return {
...token,
sessionExpirationTime: new Date(token.sessionExpirationTime),
tokenExpirationTime: new Date(token.tokenExpirationTime),
};
}
```
------
## Beobachten von Verbindungsaktualisierungen
Das Reagieren auf Änderungen im Verbindungsstatus eines Chatrooms ist ein wesentlicher Bestandteil der Entwicklung einer Chat-App. Fangen wir mit dem Abonnieren relevanter Ereignisse an:
```
// App.jsx / App.tsx
import React, { useState, useEffect } from 'react';
import { ChatRoom } from 'amazon-ivs-chat-messaging';
import { fetchChatToken } from './fetchChatToken';
export default function App() {
const [room] = useState(
() =>
new ChatRoom({
regionOrUrl: process.env.REGION as string,
tokenProvider: () => fetchChatToken('Mike', ['SEND_MESSAGE']),
}),
);
useEffect(() => {
const unsubscribeOnConnecting = room.addListener('connecting', () => {});
const unsubscribeOnConnected = room.addListener('connect', () => {});
const unsubscribeOnDisconnected = room.addListener('disconnect', () => {});
return () => {
// Clean up subscriptions.
unsubscribeOnConnecting();
unsubscribeOnConnected();
unsubscribeOnDisconnected();
};
}, [room]);
return
Hello!
;
}
```
Als Nächstes müssen wir die Möglichkeit bieten, den Verbindungsstatus zu lesen. Wir verwenden den Hook `useState`, um einen lokalen Status in `App` zu erstellen und den Verbindungsstatus in den einzelnen Listenern festzulegen.
------
#### [ TypeScript ]
```
// App.tsx
import React, { useState, useEffect } from 'react';
import { ChatRoom, ConnectionState } from 'amazon-ivs-chat-messaging';
import { fetchChatToken } from './fetchChatToken';
export default function App() {
const [room] = useState(
() =>
new ChatRoom({
regionOrUrl: process.env.REGION as string,
tokenProvider: () => fetchChatToken('Mike', ['SEND_MESSAGE']),
}),
);
const [connectionState, setConnectionState] = useState('disconnected');
useEffect(() => {
const unsubscribeOnConnecting = room.addListener('connecting', () => {
setConnectionState('connecting');
});
const unsubscribeOnConnected = room.addListener('connect', () => {
setConnectionState('connected');
});
const unsubscribeOnDisconnected = room.addListener('disconnect', () => {
setConnectionState('disconnected');
});
return () => {
unsubscribeOnConnecting();
unsubscribeOnConnected();
unsubscribeOnDisconnected();
};
}, [room]);
return
;
}
```
------
Zeigen Sie, nachdem Sie ihn abonniert haben, den Verbindungsstatus an und stellen Sie mithilfe der Methode `room.connect` im Hook `useEffect` eine Verbindung zum Chatroom her:
```
// App.jsx / App.tsx
// ...
useEffect(() => {
const unsubscribeOnConnecting = room.addListener('connecting', () => {
setConnectionState('connecting');
});
const unsubscribeOnConnected = room.addListener('connect', () => {
setConnectionState('connected');
});
const unsubscribeOnDisconnected = room.addListener('disconnect', () => {
setConnectionState('disconnected');
});
room.connect();
return () => {
unsubscribeOnConnecting();
unsubscribeOnConnected();
unsubscribeOnDisconnected();
};
}, [room]);
// ...
return (
Connection State: {connectionState}
);
// ...
```
Damit haben Sie erfolgreich eine Verbindung zum Chatroom hergestellt.
## Erstellen einer Schaltflächenkomponente zum Senden
In diesem Abschnitt erstellen Sie eine Schaltfläche zum Senden, die für jeden Verbindungsstatus anders aussieht. Diese Schaltfläche ermöglicht das Senden von Nachrichten in einem Chatroom. Sie dient auch als optisches Signal dafür, ob/wann Nachrichten gesendet werden können, z. B. bei unterbrochenen Verbindungen oder abgelaufenen Chatsitzungen.
Erstellen Sie zunächst eine neue Datei im Verzeichnis `src` Ihres Chatterbox-Projekts und geben Sie ihr den Namen `SendButton`. Erstellen Sie anschließend eine Komponente, die eine Schaltfläche für Ihre Chatanwendung anzeigt. Exportieren Sie die `SendButton` und importieren Sie sie in `App`. Fügen Sie in den leeren ``-Tags die Zeichenfolge `` hinzu.
------
#### [ TypeScript ]
```
// SendButton.tsx
import React from 'react';
interface Props {
onPress?: () => void;
disabled?: boolean;
}
export const SendButton = ({ onPress, disabled }: Props) => {
return (
);
};
// App.tsx
import { SendButton } from './SendButton';
// ...
return (
);
```
------
Definieren Sie als Nächstes in `App` eine Funktion namens `onMessageSend` und übergeben Sie sie an die Eigenschaft `SendButton onPress`. Definieren Sie eine weitere Variable namens `isSendDisabled` (die das Senden von Nachrichten verhindert, wenn der Chatroom nicht verbunden ist) und übergeben Sie sie an die Eigenschaft `SendButton disabled`.
```
// App.jsx / App.tsx
// ...
const onMessageSend = () => {};
const isSendDisabled = connectionState !== 'connected';
return (
Connection State: {connectionState}
);
// ...
```
## Erstellen einer Nachrichteneingabe
Die Chatterbox-Nachrichtenleiste ist die Komponente, über die Nachrichten an einen Chatroom gesendet werden. In der Regel enthält sie eine Texteingabe zum Verfassen der Nachricht und eine Schaltfläche für deren Versand.
Um eine `MessageInput`-Komponente zu erstellen, erstellen Sie zunächst eine neue Datei im Verzeichnis `src` und geben Sie ihr den Namen `MessageInput`. Erstellen Sie anschließend eine Eingabekomponente, die eine Eingabe für Ihre Chatanwendung anzeigt. Exportieren Sie die `MessageInput` und importieren Sie sie in `App` (oberhalb von ``).
Erstellen Sie einen neuen Status namens `messageToSend` mit dem Hook `useState` (mit einer leeren Zeichenfolge als Standardwert). Übergeben Sie im Hauptteil Ihrer App `messageToSend` an den `value` von `MessageInput` und `setMessageToSend` an die Eigenschaft `onMessageChange`:
------
#### [ TypeScript ]
```
// MessageInput.tsx
import * as React from 'react';
interface Props {
value?: string;
onValueChange?: (value: string) => void;
}
export const MessageInput = ({ value, onValueChange }: Props) => {
return (
onValueChange?.(e.target.value)} placeholder="Send a message" />
);
};
// App.tsx
// ...
import { MessageInput } from './MessageInput';
// ...
export default function App() {
const [messageToSend, setMessageToSend] = useState('');
// ...
return (
);
```
------
## Nächste Schritte
Nachdem Sie nun eine Nachrichtenleiste für Chatterbox erstellt haben, fahren Sie mit Teil 2 dieses JavaScript-Tutorials fort: [Nachrichten und Ereignisse](chat-sdk-js-tutorial-messages-events.md).