# Rollen in Erweiterungen der Nutzeroberfläche verwenden
Erfahren Sie, wie Sie Nutzerrollen in Erweiterungen der Nutzeroberfläche aufnehmen können, um die Funktionalität an verschiedene Rollen anzupassen.
Erweiterungen der Nutzeroberfläche in Stripe Apps können die Rolle des aktiven Nutzers/der aktiven Nutzerin im Dashboard lesen. Apps können für verschiedene Nutzerrollen unterschiedliche Funktionen bereitstellen.
Das SDK für Erweiterungen der Nutzeroberfläche stellt wertvolle Informationen über die Endkunden und Endkundinnen Ihrer App bereit. Das Feld `roles` des `userContext`-Objekts enthält eine Liste der aktiven Nutzerrollen. Sie können den Inhalt der App basierend auf der Rolle des Nutzers/der Nutzerin anpassen, indem Sie die Rollen im Nutzerkontext verwenden.
Verwenden Sie zusätzlich zu den Rollen `appContext.authorizedPermissions`, um zu überprüfen, über welche Berechtigungen die App für den aktuellen Kontext verfügt. Eine vollständige Liste der Felder finden Sie unter `appContext` in der [API für die Erweiterungs-SDK der Nutzeroberfläche](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md).
## So ermitteln Sie die Dashboard-Rolle des Nutzers/der Nutzerin
Erweiterungen verfügen über die Eigenschaft `userContext`, die mit Informationen über den/die aktive/n Dashboard-Nutzer/in gefüllt ist. Dieses Objekt verfügt über das Feld `roles`, bei dem es sich um ein Array mit `RoleDefinition`-Objekten für jede Rolle handelt, die dem/der aktiven Nutzer/in zugeordnet wird.
Eine Rollendefinition hat folgende Felder:
| Name des Felds | Typ | Beispiel | **Description** |
| --- | --- | --- | --- |
| Typ | ‘builtIn’ | ‘custom’ | builtIn | Gibt den Rollentyp an. Benutzerdefinierte Rollen sind nur für [private Apps](https://docs.stripe.com/stripe-apps/distribution-options.md#share-with-team-members) verfügbar. |
| id | Zeichenfolge | Entwickler/in | Eine stabile, maschinenlesbare Kennung für die Nutzerfunktion. Im Gegensatz zu `name` ändert sich dieser Wert nicht, wenn Funktionsnamen aktualisiert werden, und kann sicher für Vergleiche verwendet werden. |
| Name | Zeichenfolge | Entwickler/in | Name der Nutzerfunktion in einfacher Sprache. Verwenden Sie `id` für programmgesteuerte Vergleiche, da sich `name` ändern kann. |
Das Feld `id` stellt eine stabile Kennung für die Nutzerfunktion bereit, die Sie verwenden können, um die Funktionalität Ihrer Nutzeroberflächen-Erweiterung anzupassen. Verwenden Sie `id` anstelle von `name` für programmgesteuerte Funktionsvergleiche, um Fehler zu vermeiden, falls sich die Funktionsnamen ändern.
## Integrierte Rollen
Stripe stellt eine Reihe integrierter Rollen bereit, die für alle Konten verfügbar sind. Diese Rollen sind sowohl in öffentlichen als auch in privaten Apps verfügbar. Die vollständige Liste der integrierten Rollen und was jede von ihnen tun kann, finden Sie unter [Nutzerrollen](https://docs.stripe.com/get-started/account/teams/roles.md).
## Nutzerdefinierte Nutzerrollen (nur für private Apps)
Custom-Rollen sind kontospezifische Rollen, die von Administratorinnen und Administratoren des Kontos im Stripe-Dashboard unter **Einstellungen** > **Team und Sicherheit** erstellt werden. Da Custom-Rollen für ein bestimmtes Konto spezifisch sind, sind sie nur für [private Apps](https://docs.stripe.com/stripe-apps/distribution-options.md#share-with-team-members) verfügbar. Als App-Entwickler/in können Sie keine Custom-Rollen erstellen oder definieren. Um Custom-Rollen in Ihrer App zu verwenden, stimmen Sie sich mit der zuständigen Person für die Kontoadministration darüber ab, welche Custom-Rollen und IDs erstellt werden sollen.
Wenn eine Custom-Rolle für Ihre App freigegeben wird, ist ihre `id` das Token der Rolle, bei dem das Präfix `role_` entfernt wurde. Beispielsweise wird eine Custom-Rolle mit dem Token `role_abc123` in `userContext.roles` als `{ id: 'abc123', type: 'custom', name: 'Shipping Manager' }` angezeigt.
Custom-Rollen werden niemals für öffentliche Apps freigegeben. Wenn Ihre App öffentlich vertrieben wird, enthält `userContext.roles` immer nur integrierte Rollen.
## Anpassen von Inhalten basierend auf der Dashboard-Rolle
Häufig werden diese Informationen für die bedingte Anzeige von Inhalten basierend auf der Nutzerrolle verwendet. Nachfolgend finden Sie eine Beispiel-App, die auf bestimmte Nutzerrollen zugeschnittene Inhalte anzeigt.
```tsx
import { Badge, Box, Inline, ContextView } from "@stripe/ui-extension-sdk/ui";
import type { ExtensionContextValue } from "@stripe/ui-extension-sdk/context";
const App = ({ userContext }: ExtensionContextValue) => {
// Use `id` for stable role comparisons instead of `name`
const isAdmin = userContext?.roles?.some(role => role.id === 'admin');
const isDeveloper = !isAdmin && userContext?.roles?.some(role => role.id === 'developer');
const isAnotherRole = !isDeveloper && !isAdmin;
return (
Active user roles: {userContext?.roles?.map(role => {role.name})}
{ isAdmin && (Only admin users can see this message.) }
{ isDeveloper && (Only developers can see this message.) }
{ isAnotherRole && (Only users who are not admins or developers can see this message.) }
);
};
export default App;
```
Das Ergebnis der Beispiel-App beim Anzeigen der App als Admin-Nutzer/in
## Zugriff basierend auf der Dashboard-Rolle einschränken
Verwenden Sie Rollenüberprüfungen, um ganze Ansichten auf bestimmte Rollen zu beschränken. Dies ist nützlich für ganzseitige Apps oder Ansichten, die nur für bestimmte Teammitglieder zugänglich sind.
Rollenbasierte Überprüfungen gelten nur für die Nutzeroberfläche. Sie steuern, was Nutzerinnen und Nutzer sehen können, aber nicht, was sie über die API tun können. Die Sandbox der App wird unabhängig von der Rolle der Nutzerin/des Nutzers geladen. Wenn Ihre App Backend-API-Aufrufe durchführt, erzwingen Sie Rollenbeschränkungen auch serverseitig.
Das folgende Beispiel rendert einen blockierten Status für Nutzerinnen und Nutzer, die nicht über die erforderliche Rolle verfügen:
```tsx
import { ContextView, Box } from "@stripe/ui-extension-sdk/ui";
import type { ExtensionContextValue } from "@stripe/ui-extension-sdk/context";
const App = ({ userContext }: ExtensionContextValue) => {
const hasAccess = userContext?.roles?.some(role => role.id === 'admin');
if (!hasAccess) {
return (
You need the Administrator role to access this feature.
);
}
return (
{/* content for admins only */}
);
};
export default App;
```
Erstellen Sie für Apps mit mehreren Ansichten, die jeweils einen Rollenschutz benötigen, eine gemeinsame Wrapper-Komponente, um eine Wiederholung der Überprüfung zu vermeiden:
```tsx
import type { ExtensionContextValue } from "@stripe/ui-extension-sdk/context";
import { ContextView, Box } from "@stripe/ui-extension-sdk/ui";
type RoleGateProps = {
userContext: ExtensionContextValue["userContext"];
allowedRoles: string[];
children: React.ReactNode;
};
const RoleGate = ({ userContext, allowedRoles, children }: RoleGateProps) => {
const hasAccess = userContext?.roles?.some(role =>
role.id !== undefined && allowedRoles.includes(role.id)
);
if (!hasAccess) {
return (
You don't have permission to use this feature.
);
}
return <>{children};
};
```
Beachten Sie bei der Implementierung von rollenbasiertem Zugriff Folgendes:
- In einigen Kontexten, wie z. B. eingebetteten Apps, kann `userContext.roles` `undefined` sein. Verwenden Sie beim Lesen immer Optional Chaining.
- Es gibt keine Unterstützung auf Manifest-Ebene für Rollenbeschränkungen. Es gibt kein Feld `allowed_roles` in `stripe-app.json`. Jede Ansicht, die geschützt werden muss, muss die Überprüfung in ihrem Komponenten-Code implementieren.
- Für öffentliche Apps sind nur integrierte Rollen-IDs verfügbar. Custom-Rollen werden stillschweigend herausgefiltert und erscheinen bei öffentlichen Apps nie in `userContext.roles`.
## See also
- [Nutzeroberfläche erstellen](https://docs.stripe.com/stripe-apps/build-ui.md)
- [API-Dokumentation für die Erweiterungs-SDK der Nutzeroberfläche](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md)
- [Nutzerrollen](https://docs.stripe.com/get-started/account/teams/roles.md)
- [Vertriebsoptionen](https://docs.stripe.com/stripe-apps/distribution-options.md)