Ruby

Audiences

`audiences.list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `list_contacts`, `add_contact`, `add_contacts`, `import_contacts`, `remove_contact` et `remove_contacts`.

Toutes les méthodes

audiences.rb

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)

Une audience est une liste nommée de contacts dans cet espace de travail. Chaque contact appartient à l'audience par défaut intégrée dès l'instant où il existe, et c'est builtin qui désigne cette ligne. Les autres sont à vous de créer, remplir et supprimer. Branchez-vous sur builtin plutôt que sur le nom, que n'importe qui peut changer.

Un appel portant sur une audience prend son id en premier argument, et remove_contact prend l'adresse en deuxième. Tout le reste est un mot-clé Ruby, et un corps de requête peut aussi être passé en un seul Hash. Les options de growth et list_contacts sont en snake_case (audience_ids:, offset_minutes:), alors que les champs d'un corps gardent les noms de l'API (emails:, contacts:). Une réponse est un Hash à clés Symbol, dans le camelCase de l'API : audience[:contactCount] lit donc le nombre.

Envoyez à une ou plusieurs audiences avec client.broadcasts.send, sur la page Diffusions. Mettre un contact dans une audience est une écriture sur l'audience plutôt que sur le contact : audiences:write est donc la seule portée vérifiée. import_contacts fait exception. Il crée des contacts, et exige donc aussi contacts:write.

add_contact prend une adresse qui est déjà un contact et refuse celle qui ne l'est pas, avec un 422 contact_not_found, levé sous forme d'OpenEmail::ValidationError. Enregistrez-la d'abord avec client.contacts.create. Ajouter quelqu'un deux fois renvoie l'appartenance déjà présente, avec son addedAt d'origine : l'appel peut donc être réessayé sans risque, et la gem le réessaie après un échec réseau.

L'audience par défaut peut être renommée et décrite comme une autre, mais elle ne peut être ni supprimée ni allégée. Les deux sont refusés par un 409 audience_immutable, levé sous forme d'OpenEmail::ConflictError avec conflict? à true. Supprimez le contact quand c'est le contact que vous voulez voir partir.

Réponse : une audience

list en renvoie une page sous forme d'OpenEmail::Page, avec items, has_more? et next_cursor, l'audience par défaut d'abord, puis les autres de la plus récente à la plus ancienne. Une page en contient 25, sauf si limit: en demande jusqu'à 100. list_all renvoie toutes les pages dans un seul Array, et iterate passe les audiences une par une à un bloc, ou renvoie un Enumerator sans bloc. get, create et update renvoient chacun une audience. list_contacts renvoie plutôt une page de contacts, les contacts eux-mêmes avec la date à laquelle chacun a rejoint l'audience plutôt que des enregistrements d'appartenance, avec list_all_contacts et iterate_contacts à côté.

idString: La référence durable, `aud_` suivi de 24 caractères hexadécimaux. Les noms ne sont pas uniques : c'est donc elle qui a sa place dans une configuration stockée.
nameString: Nettoyé des espaces à l'écriture, de 1 à 120 caractères. Deux audiences peuvent porter le même nom, puisqu'une audience s'adresse par son id.
descriptionString or nil: Texte libre pour qui lira la liste plus tard. nil quand personne n'en a écrit, et `description: nil` sur `update` l'efface.
builtinString or nil: `default` sur exactement une ligne par espace de travail, l'audience qui contient chaque contact, et nil sur chaque audience créée par quelqu'un. Comparez-le avec `"default"` plutôt que de tester nil, pour qu'une audience intégrée ajoutée plus tard ne soit pas prise pour l'audience par défaut.
contactCountInteger: Combien de contacts compte l'audience, calculé au moment de la lecture plutôt que mis en cache. Deux lectures de part et d'autre d'un `contacts.create` diffèrent de un.
lastContactAtString or nil: ISO 8601 UTC, quand le contact arrivé le plus récemment a rejoint cette audience. nil tant que l'audience est vide.
createdAtString: ISO 8601 UTC, quand l'audience a été créée. Fixe l'ordre de la liste après l'audience par défaut.
updatedAtString: ISO 8601 UTC, avancé par un renommage ou un changement de description. Les changements d'appartenance n'y touchent pas.

Paramètres : audiences.list_contacts

limitInteger: Combien de contacts par page, un entier de 1 à 200, 50 par défaut.
cursorString: Le `next_cursor` de la page précédente, envoyé avec les mêmes `q:`, `source:`, `sort:` et `statuses:`. Un curseur désignant un contact qui n'est pas dans cette audience donne un 400 `invalid_cursor`, levé sous forme d'`OpenEmail::InvalidRequestError`.
qString: Cherche dans le nom et l'adresse, jusqu'à 200 caractères. Si rien ne correspond exactement sur la première page, des orthographes proches sont renvoyées à la place, et les pages suivantes continuent de chercher de la même façon.
sourceString: `manual` pour les contacts que quelqu'un a enregistrés exprès, `auto` pour ceux que le compositeur de l'application a enregistrés. Omettez-le pour tous les membres de l'audience.
sortString: `last-heard-newest` (par défaut) et `last-heard-oldest` suivent `lastSeenAt`, et les contacts à qui rien n'a jamais été envoyé arrivent en dernier dans le premier et en premier dans le second. `added-newest` et `added-oldest` suivent la date à laquelle chaque contact a rejoint cette audience, et `name` ignore la casse et trie un contact sans nom par son adresse.
statusesArray<String>: `["subscribed"]` garde les membres qui ne se sont pas désabonnés et `["unsubscribed"]` ceux qui l'ont fait. Omettez-le, passez un Array vide, ou nommez les deux, pour tous les membres de l'audience. `OpenEmail::AUDIENCE_MEMBER_STATUSES` contient les valeurs, et la gem les envoie jointes par des virgules dans le paramètre de requête `status`.

Réponse : un contact dans une audience

list_contacts renvoie une OpenEmail::Page de Hashes de contacts, et list_all_contacts et iterate_contacts parcourent toutes les pages avec les mêmes mots-clés. Chaque ligne est un contact sous la forme que renvoie contacts.list, dont les champs sont décrits sur la page Contacts, avec deux champs de plus. Parcourir toutes les pages est la façon d'exporter une audience.

addedAtString: ISO 8601 UTC, le moment où le contact a rejoint cette audience. Retirer un contact puis le rajouter le fait repartir de zéro.
unsubscribedAtString or nil: ISO 8601 UTC, quand le contact s'est désabonné d'une diffusion envoyée à cette audience, ou nil tant qu'il est abonné. Un contact désabonné reste dans l'audience, et les diffusions à celle-ci l'ignorent. Le retirer puis le rajouter le réabonne.

Ajouter et retirer en masse

add_contacts et remove_contacts prennent emails:, un Array de 1 à 200 adresses, et modifient une audience en une seule requête. add_contacts ne crée jamais de contact. Une adresse qui n'en est pas un revient dans missing, et import_contacts est l'appel qui les crée. Les deux peuvent être répétés sans risque : la gem les réessaie donc après un échec réseau, et un réessai signale les mêmes personnes comme déjà traitées au lieu d'échouer.

Ajouter à l'audience par défaut répond added: 0, car chaque contact y est déjà, et remove_contacts sur elle est refusé avec 409 audience_immutable. Retirer quelqu'un d'une audience le laisse dans le carnet d'adresses, dans l'audience par défaut et dans ses autres audiences.

audienceIdString: L'audience modifiée par l'appel, sur les deux résultats.
addedInteger: Sur le résultat d'`add_contacts` : les nouvelles appartenances créées par cet appel.
unchangedInteger: Sur le résultat d'`add_contacts` : les contacts qui étaient déjà dans l'audience. Rien n'a été écrit pour eux.
removedInteger: Sur le résultat de `remove_contacts` : les appartenances que cet appel a retirées.
notInAudienceArray<String>: Sur le résultat de `remove_contacts` : les contacts qui n'étaient pas dans l'audience, et à qui il n'est donc rien arrivé.
missingArray<String>: Sur les deux : les adresses qui ne sont pas des contacts dans cet espace de travail, en minuscules et sans doublons.

Importer

import_contacts est l'import CSV de la page de l'audience. Il prend contacts:, un Array de 1 à 500 Hashes, chacun avec un email et un name optionnel. Chaque adresse bien formée devient un contact si elle n'en est pas déjà un, et chacune arrive dans l'audience. Envoyez une liste plus longue en plusieurs appels. Il exige audiences:write et contacts:write, et une clé à laquelle l'une manque est refusée avec un 403 insufficient_scope, où scope_missing? vaut true sur l'erreur.

Une adresse qui est déjà un contact est réutilisée et garde son nom, et un name ici ne fait que remplir un nom vide. Un nouveau contact est enregistré comme manual et rejoint aussi l'audience par défaut, et une adresse qui avait été supprimée du carnet revient. Rejouer les mêmes lignes ne crée rien deux fois : la gem réessaie donc l'appel après un échec réseau.

audienceIdString: L'audience dans laquelle les lignes sont allées.
createdInteger: Les nouveaux contacts enregistrés par cet appel.
addedInteger: Les nouvelles appartenances à cette audience, y compris les contacts qui existaient déjà et n'y étaient pas encore.
skippedInteger: Les lignes qui n'ont pas été importées parce que l'adresse était mal formée.
invalidArray<String>: Les adresses mal formées, exactement comme elles ont été envoyées.

Vider

empty(id) retire tous les contacts d'une audience en une seule requête et renvoie l'audience dans son état actuel, avec contactCount à 0, plus removed, le nombre d'appartenances retirées. L'audience garde son id, son nom et sa description, et chaque contact reste dans le carnet d'adresses et dans ses autres audiences.

Cette opération est irréversible et rien n'enregistre qui figurait dans la liste : parcourez donc d'abord list_all_contacts si vous risquez de vouloir la retrouver. L'audience par défaut ne peut pas être vidée, et l'appel est refusé avec un 409 audience_immutable. La gem ne réessaie pas empty après un échec réseau, car un deuxième appel réussit avec removed: 0. Si une réponse s'est perdue, lisez l'audience avec get.

Croissance

growth lit combien de contacts ont rejoint chaque audience sur une fenêtre qui se termine maintenant, et combien s'y sont désabonnés, par jour, heure ou minute. C'est le graphique de la page des audiences. Il prend des mots-clés, exige audiences:read et renvoie un Hash.

audience_growth.rb

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"end

Une audience enregistre quand quelqu'un l'a rejointe et jamais quand il l'a quittée, donc chaque chiffre compte les personnes encore dans la liste aujourd'hui, selon leur date d'arrivée, et une courbe ne baisse jamais. Un contact qui a rejoint puis est parti n'apparaît dans aucun des chiffres.

Paramètres

audience_idsArray<String>: Jusqu'à 50 ids d'audiences, envoyés joints par des virgules. Omettez-le, ou passez un Array vide, pour toutes les audiences. Un id qui n'est pas une audience de cet espace de travail donne un 404 `audience_not_found`, et plus de 50 donnent un 422.
daysInteger: Jusqu'où remonte la fenêtre, de 1 à 1095. Elle vaut 30 quand ni `days:` ni `minutes:` n'est donné.
minutesInteger: La fenêtre en minutes, de 1 à 1576800, pour une fenêtre de moins d'un jour. Elle l'emporte sur `days:` quand les deux sont donnés.
grainString: La taille de chaque tranche : `day` (par défaut), `hour` ou `minute`.
offset_minutesInteger: Le décalage du lecteur par rapport à UTC en minutes, de -840 à 840, pour que les intervalles de jour et d'heure commencent à leur limite locale. 0 par défaut. `Time.now.utc_offset / 60` est le décalage de la machine sur laquelle le code s'exécute.

Réponse

sinceString: ISO 8601 UTC, le début du premier intervalle.
untilString: ISO 8601 UTC, le moment de la lecture.
totalsHash: `contacts` compte chaque personne une fois, quel que soit le nombre de listes où elle figure, et `memberships` additionne les listes, de sorte qu'une personne compte une fois pour chaque liste lue qui la contient. `added` totalise les arrivées dans la fenêtre, `lists` est le nombre d'audiences lues, et `busiest` est l'intervalle qui compte le plus d'arrivées, ou nil. `subscribed` compte chaque personne encore abonnée à au moins une des audiences lues, et `unsubscribed` additionne les désabonnements dans la fenêtre.
seriesArray<Hash>: Une entrée par audience, la plus grande d'abord, puis par nom : `id`, `name`, `builtin`, `total` membres actuels, `subscribed` (ceux qui sont encore abonnés), `before` (ceux qui ont rejoint avant `since`), `added` (ceux qui ont rejoint dans la fenêtre), `unsubscribed` (ceux qui s'y sont désabonnés) et `buckets`, du plus ancien au plus récent, chacun étant un Hash avec `bucket`, `added` et `unsubscribed`. Ici, `builtin` vaut `true` sur l'audience par défaut et `false` sur les autres, et non la String que porte un Hash d'audience. Seuls les intervalles comptant une arrivée ou un désabonnement sont listés, avec pour clé `YYYY-MM-DD`, `YYYY-MM-DDTHH` ou `YYYY-MM-DDTHH:MM` dans l'heure locale du décalage.