Skip to main content
Die Ads-Operationen erhalten die Ads-Plattform als Argument, sodass dieselbe Operation auf jeder von Ayrshare unterstützten Ads-Plattform funktioniert. Aktuell sind das FACEBOOK und INSTAGRAM. Jede Operation ruft den passenden REST-Ads-Endpunkt auf und gibt dessen Antwort unverändert zurück. Authentifizierung und Limits sind dieselben wie bei REST. Ein fehlgeschlagener Aufruf gibt einen GraphQL-Fehler zurück: extensions.status enthält den REST-Status und extensions.code den Ayrshare-Fehlercode, sofern der REST-Fehler einen hat. Siehe Fehler. Ads-Operationen erfordern das Ads-Add-on. Ohne dieses gibt jeder Aufruf einen Fehler mit extensions.status 403 und extensions.code 399 zurück.

​
Operationen

Jede Operation akzeptiert außerdem ein optionales profileKey, um auf ein User Profile (Benutzerprofil) zu wirken. Alle geben die REST-Antwort als JSON zurück und erlauben daher keine Feldauswahl.

​
Werbekonten auflisten

Beginnen Sie hier. Verwenden Sie die accountId-Werte aus der Antwort überall dort, wo eine Operation nach accountId fragt.

​
Targeting-Optionen suchen

kind legt die Suche fest: INTERESTS für das Zielgruppen-Targeting, REGIONS oder CITIES für Standorte. Jede Art akzeptiert nur ihre eigenen Argumente. So funktionieren countryCode und regionId beispielsweise nur mit CITIES, und INTERESTS erfordert search.

​
Anzeigen auflisten

Übergeben Sie mindestens eines der Argumente campaignId, accountId, adId, postId oder socialPostId. socialPostId ist die eigene Beitrags-ID des Netzwerks, für Beiträge, die nicht über Ayrshare veröffentlicht wurden.

​
Sehen, was eine Anzeige gekostet hat

​
Eine Anzeige pausieren oder fortsetzen

updateAd verändert echte Werbeausgaben. PAUSED stoppt die Ausgaben, ACTIVE setzt sie fort, und DELETED oder ARCHIVED beendet die Anzeige endgültig. Derselbe Status wird auch für die Anzeigengruppe und die Kampagne der Anzeige gesetzt, sodass sich alle anderen Anzeigen in dieser Anzeigengruppe oder Kampagne ebenfalls ändern. Eine Kampagne oder Anzeigengruppe, an die der Boost mit attachTo angehängt wurde, behält ihren eigenen Status, und die Anzeige läuft nur, solange die übergeordnete Kampagne und Anzeigengruppe aktiv sind.

​
Einen Beitrag bewerben

boostPost gibt echtes Geld vom Werbekonto aus. Es macht aus einem veröffentlichten Beitrag eine Anzeige.
  • Übergeben Sie postId (die Ayrshare-Beitrags-ID) oder socialPostId (die eigene Beitrags-ID des Netzwerks).
  • Die accountId erhalten Sie aus adAccounts.
  • budget.amount wird in der Währung des Werbekontos angegeben. Lassen Sie budget nur weg, wenn attachTo.adSetId die Anzeige zu einer Anzeigengruppe hinzufügt, die Sie bereits betreiben und die ihr eigenes Budget behält. Lassen Sie dann auch targeting weg: Die Anzeigengruppe behält ihr eigenes. Siehe Zu einer bestehenden Kampagne oder Anzeigengruppe hinzufügen.
  • schedule, targeting, callToAction, attachTo und status sind optional. Wenn Sie status und schedule weglassen, ist die Anzeige aktiv, startet sofort und hat kein Enddatum, sodass sie so lange Geld ausgibt, bis Sie sie pausieren. Setzen Sie status: PAUSED oder schedule.end, um sie zu begrenzen.
  • Einstellungen, die nur eine Plattform hat, gehören unter platformOptions, nach Plattform geordnet. Auf Facebook und Instagram sind dort adName und bidAmount erforderlich, zum Beispiel platformOptions: { facebook: { adName: "Autumn sale", bidAmount: 2 } }. Ohne sie gibt das Bewerben einen Fehler wegen fehlender Felder zurück. Lassen Sie bei attachTo.adSetId bidAmount weg: Die Anzeigengruppe behält ihr eigenes Gebot.
Einige Argumente akzeptieren mehr als eine Form und verwenden daher den Typ JSON:
  • accountId akzeptiert einen String oder eine Zahl.
  • Die schedule-Daten akzeptieren ein Datum oder einen Datums-Zeitwert im Format ISO 8601, etwa "2026-10-10T09:00:00Z". Verwenden Sie diese Form statt einer Zahl. schedule.end akzeptiert außerdem 0 für kein Enddatum.
  • Standortschlüssel akzeptieren einen einzelnen Wert oder eine Liste.
  • targeting.interests akzeptiert IDs als Strings oder Zahlen.
  • platformOptions akzeptiert ein Objekt.
Senden Sie bei jedem Bewerben einen neuen idempotencyKey, etwa eine UUID. Wenn ein Aufruf eine Zeitüberschreitung hat oder fehlschlägt, wiederholen Sie ihn mit demselben Schlüssel und denselben Argumenten.
  • Wenn das erste Bewerben abgeschlossen wurde, gibt die Wiederholung dessen Antwort zurück, statt eine zweite Anzeige zu erstellen und zu bezahlen.
  • Wenn das erste Bewerben noch läuft, gibt die Wiederholung einen Fehler mit extensions.status 409 zurück. Warten Sie und wiederholen Sie den Aufruf dann mit demselben Schlüssel. Wechseln Sie nicht zu einem neuen Schlüssel.
  • Wird ein Schlüssel mit anderen Argumenten wiederverwendet, wird ebenfalls 409 zurückgegeben.
Um die Ausgaben der Anzeige zu stoppen, rufen Sie updateAd mit status: PAUSED auf. boostFacebookPost und instagramBoostPost funktionieren weiterhin. Die plattformspezifischen Operationen wie facebookAdAccounts und instagramAds funktionieren weiterhin und sind unverändert.