Zielgruppen
`audiences.list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `list_contacts`, `add_contact`, `add_contacts`, `import_contacts`, `remove_contact` und `remove_contacts`.
Jede Methode
audiences = client.audiences.list_alleveryone = audiences.find { |audience| audience[:builtin] == "default" } list = client.audiences.create( name: "Product updates", description: "Customers who asked to hear about releases") client.contacts.create(email: "[email protected]", name: "Grace Hopper")client.audiences.add_contact(list[:id], email: "[email protected]") bulk = client.audiences.add_contacts(list[:id], emails: ["[email protected]", "[email protected]"]) imported = client.audiences.import_contacts( list[:id], contacts: [{email: "[email protected]", name: "Katherine Johnson"}]) members = client.audiences.list_all_contacts(list[:id], q: "grace", sort: "added-newest", limit: 200) growth = client.audiences.growth(audience_ids: [list[:id]], days: 30) client.audiences.update(list[:id], name: "Release notes")client.audiences.remove_contact(list[:id], "[email protected]")client.audiences.remove_contacts(list[:id], emails: ["[email protected]"])client.audiences.empty(list[:id])client.audiences.delete(list[:id]) puts everyone[:contactCount] if everyoneputs bulk[:missing], imported[:created], members.size, growth.dig(:totals, :added)Eine Audience ist eine benannte Kontaktliste in diesem Workspace. Jeder Kontakt gehört ab dem Moment seiner Existenz zur eingebauten Standard-Audience, und builtin ist das, was diese Zeile benennt. Die übrigen legen Sie selbst an, füllen und löschen sie. Verzweigen Sie über builtin statt über den Namen, den jeder ändern kann.
Ein Aufruf auf einer Audience nimmt deren id als erstes Argument, und remove_contact nimmt die Adresse als zweites. Alles andere ist ein Ruby-Keyword, und ein Request-Body kann auch als einzelner Hash übergeben werden. Die Optionen von growth und list_contacts sind snake_case (audience_ids:, offset_minutes:), während die Felder eines Bodys die Namen der API behalten (emails:, contacts:). Eine Antwort ist ein Hash mit Symbol-Schlüsseln im camelCase der API, audience[:contactCount] liest also die Anzahl.
Senden Sie an eine oder mehrere Audiences mit client.broadcasts.send, auf der Seite Broadcasts. Einen Kontakt in eine Audience zu stellen ist ein Schreibvorgang an der Audience, nicht am Kontakt, deshalb wird nur audiences:write geprüft. import_contacts ist die Ausnahme. Es legt Kontakte an und braucht daher auch contacts:write.
add_contact nimmt eine Adresse, die bereits ein Kontakt ist, und lehnt eine ab, die es nicht ist, mit einem 422 contact_not_found, ausgelöst als OpenEmail::ValidationError. Speichern Sie sie zuerst mit client.contacts.create. Wer jemanden zweimal hinzufügt, erhält die bereits bestehende Mitgliedschaft samt ihrem ursprünglichen addedAt zurück. Der Aufruf lässt sich also gefahrlos wiederholen, und das Gem wiederholt ihn nach einem Netzwerkfehler.
Die Standard-Audience lässt sich wie jede andere umbenennen und beschreiben, aber sie lässt sich nicht löschen und nicht ausdünnen. Beides wird mit 409 audience_immutable abgelehnt, ausgelöst als OpenEmail::ConflictError mit conflict? true. Löschen Sie den Kontakt, wenn der Kontakt gehen soll.
Antwort: eine Audience
list gibt eine Seite davon als OpenEmail::Page zurück, mit items, has_more? und next_cursor, die Standard-Audience zuerst und der Rest neueste zuerst. Eine Seite enthält 25, sofern limit: nicht bis zu 100 anfordert. list_all gibt alle Seiten in einem einzigen Array zurück, und iterate übergibt eine Audience nach der anderen an einen Block oder gibt ohne Block einen Enumerator zurück. get, create und update geben jeweils eine Audience zurück. list_contacts gibt stattdessen eine Seite von Kontakten zurück, also die Kontakte selbst mit dem Datum, an dem jeder beigetreten ist, und keine Mitgliedschaftsdatensätze, mit list_all_contacts und iterate_contacts daneben.
idString- Der dauerhafte Bezeichner, `aud_` gefolgt von 24 Hexzeichen. Namen sind nicht eindeutig, das hier gehört also in eine gespeicherte Konfiguration.
nameString- Beim Schreiben getrimmt, 1 bis 120 Zeichen. Zwei Audiences dürfen sich einen Namen teilen, denn eine Audience wird über ihre id adressiert.
descriptionString or nil- Freier Text für alle, die die Liste später lesen. nil, wenn niemand etwas geschrieben hat, und `description: nil` bei `update` löscht ihn.
builtinString or nil- `default` auf genau einer Zeile pro Workspace, der Audience, die jeden Kontakt enthält, und nil bei jeder Audience, die jemand angelegt hat. Vergleichen Sie mit `"default"`, statt auf nil zu prüfen, damit eine später hinzugefügte eingebaute Audience nicht für die Standard-Audience gehalten wird.
contactCountInteger- Wie viele Kontakte in der Audience sind, gezählt im Moment des Lesens und nicht gecacht. Zwei Lesevorgänge beiderseits eines `contacts.create` weichen um eins voneinander ab.
lastContactAtString or nil- ISO 8601 UTC, wann der zuletzt beigetretene Kontakt dieser Audience beigetreten ist. nil, solange die Audience leer ist.
createdAtString- ISO 8601 UTC, wann die Audience angelegt wurde. Bestimmt die Listenreihenfolge nach der Standard-Audience.
updatedAtString- ISO 8601 UTC, angehoben durch eine Umbenennung oder eine Beschreibungsänderung. Mitgliedschaftsänderungen rühren es nicht an.
Parameter: audiences.list_contacts
limitInteger- Wie viele Kontakte pro Seite, eine ganze Zahl von 1 bis 200, Standard 50.
cursorString- Der `next_cursor` der vorigen Seite, gesendet mit denselben `q:`, `source:`, `sort:` und `statuses:`. Ein Cursor, der einen Kontakt nennt, der nicht in dieser Audience ist, ergibt einen 400 `invalid_cursor`, ausgelöst als `OpenEmail::InvalidRequestError`.
qString- Durchsucht Name und Adresse, bis zu 200 Zeichen. Passt auf der ersten Seite nichts genau, kommen stattdessen ähnliche Schreibweisen zurück, und die folgenden Seiten suchen auf dieselbe Weise weiter.
sourceString- `manual` für die Kontakte, die jemand bewusst gespeichert hat, `auto` für die, die der Composer der App erfasst hat. Lassen Sie es weg, um alle in der Audience zu erhalten.
sortString- `last-heard-newest` (Standard) und `last-heard-oldest` richten sich nach `lastSeenAt`, und Kontakte, an die nie Mail ging, stehen im ersten Fall am Ende und im zweiten am Anfang. `added-newest` und `added-oldest` richten sich danach, wann jeder Kontakt dieser Audience beigetreten ist, und `name` ignoriert Groß- und Kleinschreibung und sortiert einen Kontakt ohne Namen nach seiner Adresse.
statusesArray<String>- `["subscribed"]` behält die Mitglieder, die sich nicht abgemeldet haben, und `["unsubscribed"]` die, die es getan haben. Lassen Sie es weg, übergeben Sie ein leeres Array oder nennen Sie beide, um alle in der Audience zu erhalten. `OpenEmail::AUDIENCE_MEMBER_STATUSES` enthält die Werte, und das Gem sendet sie mit Kommas verbunden als Query-Parameter `status`.
Antwort: ein Kontakt in einer Audience
list_contacts gibt eine OpenEmail::Page mit Kontakt-Hashes zurück, und list_all_contacts und iterate_contacts durchlaufen mit denselben Keywords alle Seiten. Jede Zeile ist ein Kontakt in der Form, die contacts.list zurückgibt, deren Felder auf der Seite Kontakte stehen, mit zwei Feldern mehr. Alle Seiten zu durchlaufen ist der Weg, eine Audience zu exportieren.
addedAtString- ISO 8601 UTC, wann der Kontakt dieser Audience beigetreten ist. Einen Kontakt herauszunehmen und wieder hinzuzufügen, lässt ihn neu beginnen.
unsubscribedAtString or nil- ISO 8601 UTC, wann sich der Kontakt von einem Broadcast an diese Audience abgemeldet hat, oder nil, solange er angemeldet ist. Ein abgemeldeter Kontakt bleibt in der Audience, und Broadcasts an sie überspringen ihn. Wenn Sie ihn herausnehmen und wieder hinzufügen, ist er neu angemeldet.
Hinzufügen und Entfernen in Massen
add_contacts und remove_contacts nehmen emails:, ein Array von 1 bis 200 Adressen, und ändern eine Audience in einer Anfrage. add_contacts legt nie einen Kontakt an. Eine Adresse, die keiner ist, kommt in missing zurück, und import_contacts ist der Aufruf, der sie anlegt. Beide lassen sich gefahrlos wiederholen, das Gem wiederholt sie daher nach einem Netzwerkfehler, und eine Wiederholung meldet dieselben Personen als bereits erledigt, statt zu scheitern.
Hinzufügen zur Standard-Audience ergibt added: 0, weil jeder Kontakt schon darin ist, und remove_contacts darauf wird mit 409 audience_immutable abgelehnt. Wer aus einer Audience genommen wird, bleibt im Adressbuch, in der Standard-Audience und in seinen anderen Audiences.
audienceIdString- Die Audience, die der Aufruf geändert hat, in beiden Ergebnissen.
addedInteger- Im Ergebnis von `add_contacts`: die neuen Mitgliedschaften aus diesem Aufruf.
unchangedInteger- Im Ergebnis von `add_contacts`: Kontakte, die schon in der Audience waren. Für sie wurde nichts geschrieben.
removedInteger- Im Ergebnis von `remove_contacts`: die Mitgliedschaften, die dieser Aufruf entfernt hat.
notInAudienceArray<String>- Im Ergebnis von `remove_contacts`: Kontakte, die nicht in der Audience waren, sodass mit ihnen nichts geschehen ist.
missingArray<String>- Bei beiden: die Adressen, die in diesem Workspace keine Kontakte sind, kleingeschrieben und ohne Wiederholungen.
Importieren
import_contacts ist der CSV-Import der Audience-Seite. Es nimmt contacts:, ein Array von 1 bis 500 Hashes, jeweils mit einer email und einem optionalen name. Jede wohlgeformte Adresse wird zum Kontakt, falls sie noch keiner ist, und jede landet in der Audience. Senden Sie eine längere Liste in mehreren Aufrufen. Es erfordert audiences:write und contacts:write, und ein Schlüssel, dem eines davon fehlt, wird mit 403 insufficient_scope abgelehnt, wobei scope_missing? am Fehler true ist.
Eine Adresse, die schon ein Kontakt ist, wird wiederverwendet und behält ihren Namen, und ein name hier füllt nur einen leeren. Ein neuer Kontakt wird als manual gespeichert und tritt auch der Standard-Audience bei, und eine Adresse, die aus dem Adressbuch gelöscht wurde, kommt zurück. Dieselben Zeilen erneut zu senden legt nichts doppelt an, das Gem wiederholt den Aufruf daher nach einem Netzwerkfehler.
audienceIdString- Die Audience, in die die Zeilen gegangen sind.
createdInteger- Neue Kontakte, die dieser Aufruf gespeichert hat.
addedInteger- Neue Mitgliedschaften in dieser Audience, einschließlich Kontakten, die schon existierten und noch nicht darin waren.
skippedInteger- Zeilen, die nicht importiert wurden, weil die Adresse fehlerhaft war.
invalidArray<String>- Die fehlerhaften Adressen, genau so, wie sie gesendet wurden.
Leeren
empty(id) nimmt in einer Anfrage jeden Kontakt aus einer Audience und gibt die Audience in ihrem jetzigen Zustand zurück, mit contactCount bei 0, plus removed, der Zahl der entfernten Mitgliedschaften. Die Audience behält ihre id, ihren Namen und ihre Beschreibung, und jeder Kontakt bleibt im Adressbuch und in seinen anderen Audiences.
Das lässt sich nicht rückgängig machen, und nichts hält fest, wer in der Liste war. Durchlaufen Sie daher zuerst list_all_contacts, wenn Sie sie vielleicht zurückhaben wollen. Die Standard-Audience kann nicht geleert werden, und der Aufruf wird mit 409 audience_immutable abgelehnt. Das Gem wiederholt empty nach einem Netzwerkfehler nicht, weil ein zweiter Aufruf mit removed: 0 gelingt. Ging eine Antwort verloren, lesen Sie die Audience mit get.
Wachstum
growth liest, wie viele Kontakte jeder Audience in einem Zeitraum bis jetzt beigetreten sind und wie viele sich darin abgemeldet haben, nach Tag, Stunde oder Minute. Es ist das Diagramm auf der Audiences-Seite. Es nimmt Keywords, erfordert audiences:read und gibt einen Hash zurück.
growth = client.audiences.growth( audience_ids: ["aud_9f2c4b7e1a0d63d84c5f2e7b"], days: 90, grain: "day", offset_minutes: Time.now.utc_offset / 60) puts "#{growth.dig(:totals, :added)} joins since #{growth[:since]}" growth[:series].each do |series| puts "#{series[:name]}: #{series[:before]} before the window, #{series[:total]} now"endEine Audience hält fest, wann jemand beigetreten ist, nie, wann er gegangen ist; jede Zahl zählt also die Personen, die heute noch in der Liste sind, nach ihrem Beitrittsdatum, und eine Linie fällt nie. Ein Kontakt, der beigetreten ist und später gegangen ist, steckt in keiner der Zahlen.
Parameter
audience_idsArray<String>- Bis zu 50 Audience-ids, mit Kommas verbunden gesendet. Lassen Sie es weg oder übergeben Sie ein leeres Array, um alle Audiences zu erhalten. Eine id, die keine Audience in diesem Workspace ist, ergibt einen 404 `audience_not_found`, und mehr als 50 ergeben einen 422.
daysInteger- Wie weit der Zeitraum zurückreicht, 1 bis 1095. Es sind 30, wenn weder `days:` noch `minutes:` angegeben ist.
minutesInteger- Der Zeitraum in Minuten, 1 bis 1576800, für einen Zeitraum unter einem Tag. Hat Vorrang vor `days:`, wenn beide angegeben sind.
grainString- Die Größe jedes Buckets: `day` (Standard), `hour` oder `minute`.
offset_minutesInteger- Der Abstand des Betrachters zu UTC in Minuten, -840 bis 840, damit Tages- und Stunden-Buckets an ihrer lokalen Grenze beginnen. Standardmäßig 0. `Time.now.utc_offset / 60` ist der Offset des Rechners, auf dem der Code läuft.
Antwort
sinceString- ISO 8601 UTC, der Beginn des ersten Buckets.
untilString- ISO 8601 UTC, der Zeitpunkt der Abfrage.
totalsHash- `contacts` zählt jede Person einmal, egal in wie vielen Listen sie ist, und `memberships` addiert die Listen auf, sodass eine Person für jede gelesene Liste, in der sie ist, einmal zählt. `added` summiert die Beitritte im Zeitraum, `lists` ist die Zahl der gelesenen Audiences, und `busiest` ist der Bucket mit den meisten Beitritten oder nil. `subscribed` zählt jede Person, die noch für mindestens eine der gelesenen Audiences angemeldet ist, und `unsubscribed` addiert die Abmeldungen innerhalb des Zeitraums.
seriesArray<Hash>- Ein Eintrag pro Audience, größte zuerst und dann nach Namen: `id`, `name`, `builtin`, `total` Mitglieder jetzt, `subscribed` (die noch angemeldet sind), `before` (die vor `since` beigetreten sind), `added` (die innerhalb des Zeitraums beigetreten sind), `unsubscribed` (die sich darin abgemeldet haben) und `buckets`, älteste zuerst, jeweils ein Hash mit `bucket`, `added` und `unsubscribed`. Hier ist `builtin` bei der Standard-Audience `true` und bei den übrigen `false`, nicht der String, den ein Audience-Hash trägt. Aufgeführt werden nur Buckets mit einem Beitritt oder einer Abmeldung, mit Schlüsseln `YYYY-MM-DD`, `YYYY-MM-DDTHH` oder `YYYY-MM-DDTHH:MM` in der Ortszeit des Offsets.