Audiences
`audiences->list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `listContacts`, `addContact`, `addContacts`, `importContacts`, `removeContact` et `removeContacts`.
Toutes les méthodes
$everyone = null; foreach ($client->audiences->listAll() as $audience) { if ($audience['builtin'] === 'default') { $everyone = $audience; }} $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->addContact($list['id'], ['email' => '[email protected]']); $bulk = $client->audiences->addContacts($list['id'], ['emails' => ['[email protected]', '[email protected]']]); $imported = $client->audiences->importContacts($list['id'], [ 'contacts' => [['email' => '[email protected]', 'name' => 'Katherine Johnson']],]); $members = $client->audiences->listAllContacts($list['id'], q: 'grace', sort: 'added-newest', limit: 200); $growth = $client->audiences->growth(audienceIds: [$list['id']], days: 30); $client->audiences->update($list['id'], ['name' => 'Release notes']);$client->audiences->removeContact($list['id'], '[email protected]');$client->audiences->removeContacts($list['id'], ['emails' => ['[email protected]']]);$client->audiences->empty($list['id']);$client->audiences->delete($list['id']); echo $everyone['contactCount'] ?? 0, ' contacts in all', PHP_EOL;echo implode(', ', $bulk['missing']), ' ', $imported['created'], ' ', count($members), ' ', $growth['totals']['added'], PHP_EOL;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 removeContact prend l'adresse en deuxième. Les filtres et les options sont des arguments nommés en camelCase (audienceIds:, offsetMinutes:), alors qu'un corps de requête est un tableau dont les clés gardent les noms de l'API (emails, contacts). Une réponse est un tableau à clés 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. importContacts fait exception. Il crée des contacts, et exige donc aussi contacts:write.
addContact 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 la forme d'une ValidationException. 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 le client 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 la forme d'une ConflictException avec isConflict() à true. Supprimez le contact quand c'est le contact que vous voulez voir partir.
Réponse : une audience
list en renvoie une page sous la forme d'une OpenEmail\Result\Page, avec items, hasMore et nextCursor, 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. listAll renvoie toutes les audiences dans un seul tableau, et iterate renvoie un Generator qui fournit les audiences une par une. get, create et update renvoient chacun une audience. listContacts 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 listAllContacts et iterateContacts à 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 null- Texte libre pour qui lira la liste plus tard. null quand personne n'en a écrit, et `'description' => null` sur `update` l'efface.
builtinstring or null- `default` sur exactement une ligne par espace de travail, l'audience qui contient chaque contact, et null sur chaque audience créée par quelqu'un. Comparez-le avec `'default'` plutôt que de tester null, pour qu'une audience intégrée ajoutée plus tard ne soit pas prise pour l'audience par défaut.
contactCountint- 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 null- ISO 8601 UTC, quand le contact arrivé le plus récemment a rejoint cette audience. null 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->listContacts
limitint- Combien de contacts par page, un entier de 1 à 200, 50 par défaut.
cursorstring- Le `nextCursor` 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 la forme d'une `InvalidRequestException`.
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.
statusesstring or array- `['subscribed']` garde les membres qui ne se sont pas désabonnés et `['unsubscribed']` ceux qui l'ont fait. Omettez-le, passez un tableau vide, ou nommez les deux, pour tous les membres de l'audience. `OpenEmail\Constants\AudienceMemberStatuses` contient les valeurs, et le client les envoie jointes par des virgules dans le paramètre de requête `status`.
Réponse : un contact dans une audience
listContacts renvoie une OpenEmail\Result\Page de tableaux de contacts, et listAllContacts et iterateContacts parcourent toutes les pages avec les mêmes arguments nommé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 null- ISO 8601 UTC, quand le contact s'est désabonné d'une diffusion envoyée à cette audience, ou null 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
addContacts et removeContacts prennent un tableau dont emails est une liste de 1 à 200 adresses, et modifient une audience en une seule requête. addContacts ne crée jamais de contact. Une adresse qui n'en est pas un revient dans missing, et importContacts est l'appel qui les crée. Les deux peuvent être répétés sans risque : le client 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 removeContacts 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.
addedint- Sur le résultat d'`addContacts` : les nouvelles appartenances créées par cet appel.
unchangedint- Sur le résultat d'`addContacts` : les contacts qui étaient déjà dans l'audience. Rien n'a été écrit pour eux.
removedint- Sur le résultat de `removeContacts` : les appartenances que cet appel a retirées.
notInAudiencearray- Sur le résultat de `removeContacts` : les contacts qui n'étaient pas dans l'audience, et à qui il n'est donc rien arrivé.
missingarray- Sur les deux : les adresses qui ne sont pas des contacts dans cet espace de travail, en minuscules et sans doublons.
Importer
importContacts est l'import CSV de la page de l'audience. Il prend un tableau dont contacts est une liste de 1 à 500 tableaux, 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ù isScopeMissing() vaut true sur l'exception.
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 : le client réessaie donc l'appel après un échec réseau.
audienceIdstring- L'audience dans laquelle les lignes sont allées.
createdint- Les nouveaux contacts enregistrés par cet appel.
addedint- Les nouvelles appartenances à cette audience, y compris les contacts qui existaient déjà et n'y étaient pas encore.
skippedint- Les lignes qui n'ont pas été importées parce que l'adresse était mal formée.
invalidarray- 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 listAllContacts 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. Le client 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 arguments nommés, exige audiences:read et renvoie un tableau.
$growth = $client->audiences->growth( audienceIds: ['aud_9f2c4b7e1a0d63d84c5f2e7b'], days: 90, grain: 'day', offsetMinutes: intdiv((int) date('Z'), 60),); echo $growth['totals']['added'], ' joins since ', $growth['since'], PHP_EOL; foreach ($growth['series'] as $series) { echo $series['name'], ': ', $series['before'], ' before the window, ', $series['total'], ' now', PHP_EOL;}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
audienceIdsstring or array- Jusqu'à 50 ids d'audiences, sous forme de liste ou d'une seule chaîne séparée par des virgules, envoyés joints par des virgules. Omettez-le, ou passez un tableau 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.
daysint- Jusqu'où remonte la fenêtre, de 1 à 1095. Elle vaut 30 quand ni `days:` ni `minutes:` n'est donné.
minutesint- 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`.
offsetMinutesint- 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. `intdiv((int) date('Z'), 60)` est le décalage du fuseau configuré dans PHP.
Réponse
sincestring- ISO 8601 UTC, le début du premier intervalle.
untilstring- ISO 8601 UTC, le moment de la lecture.
totalsarray- `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 null. `subscribed` compte chaque personne encore abonnée à au moins une des audiences lues, et `unsubscribed` additionne les désabonnements dans la fenêtre.
seriesarray- 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 tableau avec `bucket`, `added` et `unsubscribed`. Ici, `builtin` vaut `true` sur l'audience par défaut et `false` sur les autres, et non la chaîne que porte un tableau 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.