> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Übersicht zur Social-Verknüpfung
> Wie Ihre Nutzer ihre Social-Media-Konten verbinden — die drei Oberflächen, die Link Session hinter allen dreien und die Optionen, die sie gemeinsam haben.
export const PlansAvailable = ({plans = [], maxPackRequired}) => {
let displayPlans = plans;
if (plans && plans.length === 1) {
const lowerCasePlan = plans[0].toLowerCase();
if (lowerCasePlan === "business") {
displayPlans = ["Launch", "Business", "Enterprise"];
} else if (lowerCasePlan === "premium") {
displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
}
}
return
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.
{maxPackRequired && window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
Max Pack required
}
;
};
Ihre Nutzer verbinden ihre eigenen Social-Media-Konten selbst — sie authentifizieren sich direkt
bei jedem Netzwerk, und Sie sehen oder speichern nie deren Zugangsdaten. Auf dieser Seite geht es
darum, sie zu diesem Moment zu bringen und zu erfahren, wie es ausgegangen ist.
Eines ist allen Wegen gemeinsam: eine **Link Session**, erstellt mit
[Eine Link Session erstellen](/docs/apis/profiles/create-link-session) aus Ihrem API Key und einem
`Profile-Key`. Auf Ihrer Seite wird nichts signiert, und es ist kein Private Key im Spiel.
## Drei Wege zum Verbinden
Drei Varianten, und die ersten beiden sind dieselbe Integration. Wählen Sie pro Ablauf — sie
schließen sich nicht aus, und viele Integrationen verwenden die gehostete Seite für das Onboarding
und danach das Widget innerhalb der App.
| Oberfläche | Ihr Nutzer sieht | White-Labeling | Wählen Sie sie, wenn |
| ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Widget — eingebettete Frames** ([mount](/docs/multiple-users/connect-widget#mount-a-slot)) | unsere Schaltflächen inline in Ihrem eigenen Layout; kein Popup bis zu dem des Netzwerks | **Am stärksten.** Ihre Seite, Ihre Schriften und Farben, und Ihr Nutzer verlässt sie nie | Sie haben ein Dashboard mit einer Zeile pro Netzwerk und möchten, dass die Verknüpfung an Ort und Stelle geschieht. Max Pack. |
| **Widget — Ihre eigene Schaltfläche** ([popup](/docs/multiple-users/connect-widget#your-own-button)) | Ihre Schaltfläche, dann ein Popup für das Netzwerk | **Stark.** Das Popup ist unseres, aber es ist kurz und übernimmt Ihr Erscheinungsbild | Sie möchten Ihre eigene Schaltfläche und Ihr eigenes Styling, und keine Frames in Ihrem Layout. Max Pack. |
| **Gehostete Verknüpfungsseite** ([Anleitung](/docs/multiple-users/api-integration-business#single-sign-on-with-jwt-authentication)) | eine von uns gehostete Seite mit Ihrem Logo, Ihren Farben und eigenem CSS | **Am schwächsten.** Es ist unsere Seite, und Ihr Nutzer verlässt Ihre, um sie zu nutzen | Sie möchten einen Link zum Weitergeben, oder Sie onboarden per E-Mail. Nichts zu bauen, kein Max Pack. |
Die beiden Widget-Zeilen sind **eine Integration**, nicht zwei. Ein einziges `init` gibt Ihnen
beides: Mounten Sie Frames dort, wo Sie unsere Schaltflächen möchten, und rufen Sie überall sonst
`popup()` aus Ihrer eigenen Schaltfläche auf. Beide teilen sich eine Session und melden sich über
dieselben Handler.
[Direct Mode](/docs/multiple-users/connect-direct-mode) ist dasselbe Popup **ohne** unser Skript — für
eine Seite mit strikter Content-Security-Policy, eine servergerenderte Seite oder eine native App.
Dort öffnen und überwachen Sie das Popup selbst.
**Nicht sicher?** Beginnen Sie mit der gehosteten Verknüpfungsseite. Sie benötigt keinen Max Pack
und keine zusätzlichen Parameter und ist der schnellste Weg zu etwas Funktionierendem — ein
späterer Wechsel zum Widget ändert nichts daran, wie Sessions erstellt werden.
## Einen Link erstellen
Rufen Sie [Eine Link Session erstellen](/docs/apis/profiles/create-link-session) mit dem `Profile-Key`
des Nutzers im Header auf. Für die gehostete Seite ist das die gesamte Anfrage:
```bash cURL theme={"system"}
curl -X POST https://api.ayrshare.com/api/profiles/link-sessions \
-H "Authorization: Bearer $AYRSHARE_API_KEY" \
-H "Profile-Key: $PROFILE_KEY" \
-H "Content-Type: application/json" \
-d '{}'
```
Sie erhalten eine `url` zurück, die ein kurzlebiges, opakes Token trägt:
```javascript Linking URL theme={"system"}
https://profile.ayrshare.com?session=ayr_ls_kJ8mQ2vX9pLnR4tYwZ6aBcD1eFgH3iJkLmN0oPqRsTu&domain=YOUR_DOMAIN
```
Sie können außerdem [prüfen, ob ein Link geöffnet wurde](/docs/apis/profiles/get-link-session), und ihn
[widerrufen](/docs/apis/profiles/revoke-link-session), bevor er abläuft.
Dieses einminütige Video zeigt, wie ein Link erstellt wird. Es wurde vor den Link Sessions
aufgenommen und zeigt daher noch, wie ein Private Key gesendet wird — dieser Schritt ist nicht
mehr erforderlich, alles andere im Video ist unverändert.
Die Linking-URL versenden
Eine Linking-URL meldet Ihren Nutzer in seinem Profil an — behandeln Sie sie wie ein Passwort.
Versenden Sie sie über einen vertrauenswürdigen Kanal, loggen Sie sie nicht und geben Sie sie
nicht an Dritte weiter. Sie bleibt für ihr gesamtes Zeitfenster nutzbar, ein Reload oder ein
OAuth-Retry funktioniert also — senden Sie jeden Link aber nur an einen Nutzer und erstellen
Sie pro Person einen eigenen Link.
### Die Linking-URL öffnen
Öffnen Sie sie in einem neuen Browser-Tab, einem neuen Fenster oder einem View Controller. Sie
können das
[Schließen oder Umleiten](/docs/multiple-users/api-integration-business#opening-and-closing-the-social-linking-url)
dieses Fensters steuern.
Die sozialen Netzwerke erlauben es nicht, die gehostete Verknüpfungsseite in einem iFrame zu
öffnen oder die freigegebene Partner-Ursprungsdomain `profile.ayrshare.com` zu verschleiern. Wenn
die Verknüpfung innerhalb Ihrer eigenen Seite stattfinden soll, ist genau dafür das
[eingebettete Widget](/docs/multiple-users/connect-widget) da: Seine Frames werden von einer
Ayrshare-Origin ausgeliefert und sind der unterstützte Weg dafür.
### Erfahren, wann es abgeschlossen ist
Zwei Signale, und Sie können jedes davon nutzen:
* **[Link-Completion-Events](/docs/multiple-users/link-completion-events)** — setzen Sie beim Erstellen
des Links ein `origin`, und das Verknüpfungsfenster sendet `connect:success`, `connect:error` und
`connect:cancelled` an Ihre Seite, sobald sie eintreten. Kein Polling.
* **[Eine Link Session abrufen](/docs/apis/profiles/get-link-session)** — meldet `completedAt`,
`lastCompletedAt` und `completedNetworks`. Das ist das Signal für native Apps und das einzige für
Telegram, das außerhalb des Browsers abgeschlossen wird.
Link-Gültigkeit
Ein Link ist standardmäßig **5 Minuten** gültig. Danach erstellen Sie einen neuen.
Mit dem Max Pack setzen Sie `expiresIn` in Minuten, um dieses Zeitfenster zu erweitern — bis zu
**2880 Minuten (48 Stunden)**, dem Maximum, das die API akzeptiert:
```json Expires In theme={"system"}
{
"expiresIn": 30
}
```
Ein längeres Zeitfenster macht das [Versenden des Links per E-Mail](#connect-accounts-email) erst
praktikabel — ein Nutzer, der ein getrenntes Konto neu verknüpft, kann direkt aus Ihrer E-Mail zum
Netzwerk gehen, ohne zuerst Ihre App zu besuchen.
Prüfen Sie mit Ihrem Sicherheitsteam, wie lange ein Link gültig bleiben soll. Ein längeres
Zeitfenster ist ein längerer Zeitraum, in dem ein abgefangener Link noch funktioniert. Gerät
einer nach außen, können Sie ihn [widerrufen](/docs/apis/profiles/revoke-link-session), statt auf
seinen Ablauf zu warten.
## Profile Key
Der `Profile-Key` gibt an, für welches User Profile der Link gilt. Sie finden ihn im
Ayrshare-Entwickler-Dashboard, indem Sie zu diesem Profil wechseln.
**Der Private Key wird nicht mehr verwendet.** Links werden nicht signiert, es gibt also nichts,
was aus einer Datei gelesen oder in Ihren Code eingefügt werden müsste. Der Legacy-Parameter
`privateKey` wird weiterhin akzeptiert und ignoriert, sodass bestehende Integrationen
weiterlaufen, und die Datei `private.key` in Ihrem Integration Package kann ungenutzt bleiben.
## Profile wechseln
Wenn ein Profil bereits angemeldet ist, wechselt das Öffnen des Links eines anderen Profils nicht
das Profil — das ist beabsichtigt und hält die Nutzung für einen bereits angemeldeten Nutzer
schnell. Um einen Wechsel zu erzwingen, siehe
[Automatische Abmeldung einer Profilsitzung](/docs/multiple-users/api-integration-business#automatic-logout-of-a-profile-session).
Instagram-Verknüpfungsmethode
Instagram-Konten können auf [zwei Arten](/docs/dashboard/connect-social-accounts/instagram) verknüpft
werden: direkt mit **Instagram Login** oder über eine **verbundene Facebook-Seite**. Welcher Ablauf
startet, wenn ein Nutzer auf die Instagram-Schaltfläche klickt, wird normalerweise durch die
kontoweite Einstellung [Instagram Login](/docs/multiple-users/manage-user-profiles#instagram-login)
gesteuert.
Der Body-Parameter `instagramLinkMethod` überschreibt diese Einstellung für einen einzelnen Link:
| Wert | Instagram-Verknüpfungsablauf |
| ----------- | ------------------------------------------------------------ |
| `instagram` | Direktes Instagram Login. Keine Facebook-Seite erforderlich. |
| `facebook` | Verknüpfung über eine verbundene Facebook-Seite. |
```json Instagram Link Method theme={"system"}
{
"instagramLinkMethod": "instagram"
}
```
Die Überschreibung gilt für die Lebensdauer dieses Links, einschließlich der
Autorisierungsweiterleitung von Instagram/Facebook. Einige Punkte, die Sie wissen sollten:
* Sie ändert nicht Ihre kontoweite Einstellung und beeinflusst keinen anderen Link.
* Lassen Sie sie weg, gilt die kontoweite Einstellung, genau wie zuvor.
* Ein ungültiger Wert gibt `400` zurück und listet die gültigen Werte auf (`instagram`, `facebook`).
* Prüfen Sie die
[Funktionsunterschiede](/docs/multiple-users/manage-user-profiles#direct-instagram-login-vs-facebook-page-authentication),
bevor Sie wählen — einige Instagram-Funktionen wie Hashtag-Suche und Kollaborationen sind nur mit
der Facebook-Seiten-Authentifizierung verfügbar.
Connect-Accounts-E-Mail
Ayrshare kann den Link für Sie per E-Mail an Ihren Nutzer senden, damit er seine Verknüpfungsseite
erreichen kann, ohne Ihre App zu besuchen. Kombinieren Sie das mit einem längeren
[`expiresIn`](#jwt-expires-in) — die standardmäßigen fünf Minuten überstehen selten ein Postfach.
### Connect Accounts JSON
**Jedes Feld innerhalb von `email` ist erforderlich.** Fehlt eines, schlägt der Versand fehl.
```json Example Contact Email Request theme={"system"}
{
"expiresIn": 60,
"email": {
"to": "john@user.com",
"contactEmail": "support@mycompany.com",
"company": "ACME",
"termsUrl": "https://www.ayrshare.com/terms",
"privacyUrl": "https://www.ayrshare.com/privacy"
}
}
```
`expiresIn` ist ein Parameter auf **oberster Ebene**, nicht Teil des `email`-Objekts. Innerhalb
von `email` verschachtelt wird es ignoriert, und Ihr Nutzer erhält einen Link, der in fünf
Minuten abläuft.
Die Antwort meldet das Ergebnis in `emailSent`:
```json Example Contact Email Response theme={"system"}
{
"status": "success",
"sessionId": "c7a2434e72e91bde27579efde0fd6dd0b74ceee29a471fd368407f273708c2e8",
"url": "https://profile.ayrshare.com?session=ayr_ls_kJ8mQ2vX9pLnR4tYwZ6aBcD1eFgH3iJkLmN0oPqRsTu&domain=YOUR_DOMAIN",
"expiresAt": "2026-09-02T09:03:26.838Z",
"emailSent": true,
"title": "Acme Client"
}
```
Ein **Sendefehler** kommt nicht als `emailSent: false` zurück — er gibt stattdessen `code: 333`
zurück. `false` bedeutet also, dass keine E-Mail angefordert wurde.
### Beispiel für eine Connect-Accounts-E-Mail
Hier ein Beispiel der E-Mail, die die Social-Verknüpfungsseite öffnet:
Die E-Mail wird von der folgenden Adresse gesendet:
`Social Connect Hub `
Mobile Apps
Öffnen Sie die Linking-URL im **Systembrowser**, nie in einer eingebetteten WebView: Google lehnt
die Anmeldung darin mit `disallowed_useragent` ab, und Meta blockiert sie vollständig. Ihr Nutzer
würde die Fehlerseite des Netzwerks sehen, und nichts auf Ihrer Seite kann das beheben.
* **iOS** — `ASWebAuthenticationSession` oder `SFSafariViewController`.
* **Android** — Chrome Custom Tabs.
Da eine native App kein Browserfenster hat, an das Events gesendet werden könnten, holen Sie sich
das Ergebnis stattdessen über [Eine Link Session abrufen](/docs/apis/profiles/get-link-session). Setzen
Sie `origin` auf Ihr eigenes Custom Scheme (`myapp://connected`), damit die Seite einen Rückweg in
Ihre App hat.
Mobile-Codebeispiele
Ersetzen Sie `linkingURL` durch die `url`, die
[Eine Link Session erstellen](/docs/apis/profiles/create-link-session) zurückgibt.
```swift Swift theme={"system"}
import UIKit
import SafariServices
class ViewController: UIViewController, SFSafariViewControllerDelegate {
var linkingURL = "https://profile.ayrshare.com?session=ayr_ls_kJ8mQ2vX9pLnR4tYwZ6aBcD1eFgH3iJkLmN0oPqRsTu&domain=acme"
override func viewDidLoad() {
super.viewDidLoad()
setupButton()
}
func setupButton() {
let button = UIButton(type: .system)
button.frame = CGRect(x: (view.bounds.width - 200) / 2, y: (view.bounds.height - 50) / 2, width: 200, height: 50)
button.setTitle("Open URL", for: .normal)
button.addTarget(self, action: #selector(buttonTapped), for: .touchUpInside)
view.addSubview(button)
}
@objc func buttonTapped() {
openURLInInAppBrowser()
}
func openURLInInAppBrowser() {
if let url = URL(string: linkingURL) {
let safariVC = SFSafariViewController(url: url)
safariVC.delegate = self
present(safariVC, animated: true, completion: nil)
}
}
// Optional: If you want to handle when the in-app browser is closed
func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
controller.dismiss(animated: true, completion: nil)
}
}
```
```dart Flutter theme={"system"}
/** yaml dependencies
dependencies:
flutter:
sdk: flutter
url_launcher: ^6.2.1
*/
import 'package:flutter/material.dart';
import 'package:url_launcher/url_launcher.dart';
void main() {
runApp(MyApp());
}
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'URL Launcher Example',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MyHomePage(),
);
}
}
class MyHomePage extends StatelessWidget {
final String linkingURL = "https://profile.ayrshare.com?session=ayr_ls_kJ8mQ2vX9pLnR4tYwZ6aBcD1eFgH3iJkLmN0oPqRsTu&domain=acme";
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: Text('URL Launcher Example'),
),
body: Center(
child: ElevatedButton(
onPressed: () {
openURLInBrowser(context);
},
child: Text('Open URL'),
),
),
);
}
void openURLInBrowser(BuildContext context) async {
if (await canLaunch(linkingURL)) {
await launch(linkingURL);
} else {
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(
content: Text('Could not launch $linkingURL'),
),
);
}
}
}
```
```jsx React Native theme={"system"}
/**
• Using the API provided by expo-web-browser,
• which opens a URL in a modal browser window that shares cookies
• with the system browser.
• Learn more about expo: https://reactnative.dev/docs/environment-setup?guide=quickstart
• and running the following command:
• expo install expo-web-browser
*/
import React from 'react';
import { StyleSheet, Button, View } from 'react-native';
import * as WebBrowser from 'expo-web-browser';
export default function App() {
const linkingURL = 'https://profile.ayrshare.com?session=ayr_ls_kJ8mQ2vX9pLnR4tYwZ6aBcD1eFgH3iJkLmN0oPqRsTu&domain=acme';
const openURLInBrowser = async () => {
try {
await WebBrowser.openBrowserAsync(linkingURL);
// Optional: WebBrowser.openBrowserAsync returns a promise that resolves with an object containing
// 'type' that can be 'cancelled' or 'dismissed'. You can use this to handle when the browser is closed.
} catch (error) {
console.error(error);
}
};
return (
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
},
});
```
## Testen
Es wird **empfohlen**, einen Link zunächst in [Postman](/docs/testing/postman) zu erstellen. Ihr
Integration Package — auf der API-Key-Seite des Primary Profile im Dashboard — enthält eine
Beispiel-Postman-Konfiguration. Importieren Sie sie, tragen Sie Ihren Profile Key im *Body*-Feld
`profileKey` ein und klicken Sie auf *Send*.
Die Beispielkonfiguration füllt `privateKey` und `domain` weiterhin vor. `privateKey` wird
ignoriert, und `domain` können Sie leeren, sofern Ihr Account nicht mehr als eine Linking-Domain
hat.
Sie können auch [den Code aus Postman generieren](/docs/testing/postman#auto-generate-api-code-with-postman).
### Bubble.io
## Legacy: generateJWT
[Linking-URL erzeugen](/docs/apis/profiles/generate-jwt) (`generateJWT`) erledigt dieselbe Aufgabe und
ist **veraltet (deprecated)** — vollständig unterstützt, ohne Abschaltdatum und unverändert für
Links, die Sie bereits herausgegeben haben. Die eigene Seite des Endpunkts dokumentiert seine
Parameter, einschließlich der drei, die inzwischen akzeptiert und ignoriert werden.
Beide Endpunkte nutzen denselben Validator, sodass alles auf dieser Seite für beide gilt. Der
eine Unterschied, den Sie bei der Migration kennen sollten: `generateJWT` toleriert drei Dinge,
die Eine Link Session erstellen ablehnt — ein unbekanntes `allowedSocial`-Netzwerk, eine einzelne
X-Zugangsdaten-Hälfte und ein nicht-String-`redirect`.
Die E-Mail wird von der folgenden Adresse gesendet:
`Social Connect Hub