Zugriff auf Ads-Konten

​

Nutzerkonten vs. Werbekonten

Bei der Nutzung der Ads API sind zwei unterschiedliche Kontotypen beteiligt: Werbekonten und X Nutzerkonten. In der gesamten Ads-API-Dokumentation bezieht sich der Begriff „Konto“ in der Regel auf das Werbekonto.

• Werbekonten werden auf business.x.com registriert und in der API durch account_id identifiziert. Sie sind direkt mit Finanzierungsquellen verknüpft und nutzen Inhalte von einem oder mehreren X Nutzerkonten als „promotable users“. Jedes Werbekonto kann einem oder mehreren X Nutzerkonten Berechtigungen erteilen. Das Werbekonto, also das „aktuelle Konto“, wird in nahezu jeder ausgeführten URL als Inline-Parameter :account_id dargestellt.
• X Nutzerkonten (z. B. @AdsAPI) werden in der Ads API durch user_id identifiziert. Eines oder mehrere dieser Konten können einem Werbekonto zugeordnet werden. Das authentifizierte X Nutzerkonto, das Anfragen an die API stellt, wird als „aktueller Nutzer“ bezeichnet. Eine Liste der Werbekonten, auf die der aktuelle Nutzer Zugriff hat, finden Sie unter GET accounts. „Promotable users“ sind X Handles, die von einem bestimmten Werbekonto beworben werden können. Weitere Details finden Sie unter Obtaining Ads Account Access.

​

Methoden für den Zugriff auf Werbekonten

Es gibt zwei Methoden, mit denen Sie Ads API-Anfragen für das Konto eines Werbetreibenden stellen können:

1. Anfragen im Namen eines Werbetreibenden stellen (empfohlen)
2. Anfragen über Ihr Konto stellen, dem Zugriff auf das Konto eines Werbetreibenden gewährt wurde, z. B. eine Agency, die mehrere Konten betreut.

Dieses Dokument bietet einen kurzen Überblick über die Unterschiede zwischen diesen Optionen und sollte zusammen mit unseren weiteren Ressourcen verwendet werden, z. B. den FAQs zum Multi-User-Login. 

Wie in Autorisieren einer Anfrage beschrieben, erfordern alle Anfragen an die Ads API Authorization-Header mit OAuth 1.0a unter Verwendung eines access token, das über den 3-leggedOAuth-Flow erhalten wurde. Ihre Anwendung muss einen webbasierten OAuth-Flow implementieren, um Access Tokens zu erhalten. Ads API-Entwickler sollten unsere X Werbetreibenden niemals auffordern, ihre Login-Zugangsdaten zu teilen.

Standardmäßig enthält jede X developer application ein statisches access token, das verwendet werden kann, um Ads API-Anfragen für das Konto zu stellen, dem die Anwendung gehört. Diese Anmeldedaten sind ideal für Anwendungsfälle mit nur einem Konto, ohne dass ein 3-legged- oder PIN-basierter OAuth-Flow erforderlich ist. Wenn Sie nicht auf ein anderes X Ads-Konto zugreifen, verwenden Sie diese Single-User Anmeldedaten anstelle der folgenden Schritte.

​

Zugriffsstufen

​

Berechtigungen auf App-Ebene

Jede Nutzerin/jeder Nutzer erhält ein Zugriffslevel entsprechend dem bei der Beantragung der Ads API angeforderten:

• Nur Conversions: Nutzerin/Nutzer hat Zugriff auf die Mobile- und Web Conversion-endpoints mit Lese- und Schreib-zugriff.
• Standardzugriff: Nutzerin/Nutzer hat Zugriff auf die Analytics-, Campaign Management-, Creatives-, Custom Audiences- und Conversion-endpoints mit Lese- und Schreib-zugriff.

Hinweis: Ads API-Entwicklerinnen und -Entwickler, die vor Juli 2023 Zugriff beantragt haben, können andere Zugriffslevel und Berechtigungen haben und ggf. auf fünf OAuth-Tokens beschränkt sein. Siehe unseren Leitfaden zum Erhöhen des Zugriffs, um Zugriff auf zusätzliche endpoints zu erhalten oder Tokenlimits für bestehende Anwendungen aufzuheben.

​

Berechtigungen auf Anzeigenkontenebene

Jeder Nutzer, der Zugriff auf ein Ads-Konto hat, verfügt über eine spezifische Berechtigung auf Kontoebene: Account administrator, Ad manager, Campaign analyst, Organic analyst und Creative Manager; die aktuelle Dokumentation zu Berechtigungen auf Kontoebene finden Sie auf business.x.com. Anwendungen sollten die Berechtigungen des aktuell authentifizierten Nutzers über das API-endpoint Authenticated User Access abrufen, um zu bestimmen, auf welche API-endpoints und Ads-Funktionen sie zugreifen können.

Hinweis: Alle Nutzertokens, die mit der Conversion API verwendet werden, müssen zu Nutzern mit Berechtigungen auf Kontoebene als Account administrator oder Ad manager gehören.                                                                                                                                              

​

Methoden zum Erlangen von access tokens

​

1. Access Token eines Werbetreibenden (User) erhalten

Es gibt zwei Methoden, um das access token eines Werbetreibenden zu erhalten. Die gängigste Methode ist ein 3-legged OAuth-Flow direkt innerhalb Ihrer Web-UI. Anwendungen ohne öffentlich zugängliche UI für Werbetreibende können einen PIN-basierten OAuth-Prozess implementieren. Nachdem der User den 3-legged Flow abgeschlossen hat, verfügt Ihre Anwendung über Berechtigungsnachweise, um über die API Anfragen für dessen Ads-Konto zu stellen.

Die Erlangung von User-Anmeldedaten über den OAuth-Flow ist die von uns nachdrücklich empfohlene Methode für die Mehrheit der Ads API-Entwickler, um Zugriff auf ein Werbetreibendenkonto zu erhalten. Sie ermöglicht es Ihnen, die API im Namen eines Users aufzurufen und in dessen Namen zu handeln. Diese Tokens laufen nicht ab, können jedoch jederzeit vom User widerrufen werden.

​

2. Rufen Sie Ihr (Developer) access token ab

Bei dieser Option muss der Werbetreibende Ihrem @username (oder mehreren @usernames) über die X‑UI unter business.x.com Zugriff auf sein X Ads-Konto gewähren. Access Tokens, die über den 3-legged OAuth-Flow für Ihr Konto erhalten wurden, können auf das X Ads-Konto des Werbetreibenden zugreifen.

So können Sie die API mit den OAuth-Tokens Ihres eigenen @username statt mit den OAuth-Tokens des Werbetreibenden aufrufen. Der entscheidende Punkt bei dieser Option ist, dass Sie nur Promoted-Only Posts erstellen können, wenn Ihrem @username die Berechtigung „Post Delegation/Composer“ erteilt wurde.

Um die Berechtigung zu erhalten, Promoted-Only Posts im Namen des FULL promotable user des Kontos zu erstellen, müssen Sie in diesem Flow ebenfalls die Berechtigung zum Erstellen von Posts erhalten. Dies ermöglicht den Zugriff über die Berechtigung TWEET_COMPOSER am endpoint GET accounts/:account_id/authenticated_user_access.

​

Unterschiede zwischen diesen Methoden

	Advertiser-(User-)OAuth-Token	(Developer-)OAuth-Token  (@username hinzugefügt, um Accounts zu unterscheiden)
Zugriff auf Ads-Account	✔	✔
Posts im Namen des Nutzers erstellen	✔	✔*
Kampagnen verwalten	✔	✔
Zugriff auf Analytics	✔	✔
Cards im Namen des Nutzers erstellen	✔	✔
Entwicklerzugriff über die X Ads UI		✔
Rate Limits	Unterschiedlich pro Advertiser	Unterschiedlich pro Advertiser-Account

Hinweis: Weitere Details finden Sie oben im Abschnitt Obtain your (Developer) access token.

​

Beispielanwendung

​

Access Token des Werbetreibenden über den webbasierten OAuth-3‑Legged-Flow

Der Standardablauf ist webbasiert und nutzt den OAuth‑Flow der 3-legged authorization. Die hier gezeigten Screenshots stammen aus einem Beispiel, dessen Quellcode Sie unter https://github.com/xdevplatform/twauth-web einsehen können.

An einem Punkt in Ihrer Anwendung leiten Sie zu X weiter, um Ihre Anwendung zu autorisieren

Wenn Sie mit dem Request-Token zu X weiterleiten, wird der Nutzer aufgefordert, Ihre Anwendung zu autorisieren

Nach der Autorisierung Ihrer Anwendung wird der Nutzer an die Callback-URL zurückgeleitet, die Sie beim Erzeugen des Request-Tokens angegeben haben. Diese verwenden Sie, um den dauerhaften Access Token für diesen Nutzer zu erhalten und lokal zu speichern.