Ruby

Audiencias

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

Todos los métodos

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)

Una audiencia es una lista de contactos con nombre dentro de este espacio de trabajo. Todo contacto está en la audiencia por defecto integrada desde el momento en que existe, y builtin es lo que identifica esa fila. Las demás son tuyas para crearlas, llenarlas y eliminarlas. Ramifica según builtin y no según el nombre, que cualquiera puede cambiar.

Una llamada sobre una audiencia recibe su id como primer argumento, y remove_contact recibe la dirección como segundo. Todo lo demás es un argumento nombrado de Ruby, y un cuerpo de solicitud también se puede pasar como un solo Hash. Las opciones de growth y list_contacts están en snake_case (audience_ids:, offset_minutes:), mientras que los campos de un cuerpo conservan los nombres de la API (emails:, contacts:). Una respuesta es un Hash con claves Symbol en el camelCase de la API, así que audience[:contactCount] lee el recuento.

Envía a una o varias audiencias con client.broadcasts.send, en la página Envíos masivos. Meter un contacto en una audiencia es una escritura sobre la audiencia y no sobre el contacto, así que audiences:write es el único ámbito que se comprueba. import_contacts es la excepción. Crea contactos, así que también necesita contacts:write.

add_contact acepta una dirección que ya es un contacto y rechaza la que no lo es, con 422 contact_not_found, lanzado como OpenEmail::ValidationError. Guárdala antes con client.contacts.create. Añadir a alguien dos veces responde con la pertenencia que ya existe, con su addedAt original, así que la llamada se puede reintentar sin riesgo, y la gema la reintenta tras un fallo de red.

La audiencia por defecto se puede renombrar y describir como cualquier otra, pero no se puede eliminar ni vaciar parcialmente. Ambas cosas se rechazan con 409 audience_immutable, lanzado como OpenEmail::ConflictError con conflict? a true. Elimina el contacto cuando lo que quieras es que se vaya el contacto.

Respuesta: una audiencia

list devuelve una página de ellas como una OpenEmail::Page, con items, has_more? y next_cursor, primero la audiencia por defecto y el resto de la más nueva a la más antigua. Una página contiene 25 salvo que limit: pida hasta 100. list_all devuelve todas las páginas en un solo Array, e iterate pasa las audiencias de una en una a un bloque, o devuelve un Enumerator sin bloque. get, create y update devuelven cada uno una audiencia. list_contacts devuelve en cambio una página de contactos, los propios contactos con la fecha en que se unió cada uno en lugar de registros de pertenencia, con list_all_contacts e iterate_contacts a su lado.

idString: El identificador duradero, `aud_` seguido de 24 caracteres hexadecimales. Los nombres no son únicos, así que esto es lo que debe ir en la configuración almacenada.
nameString: Se recortan los espacios al escribir, de 1 a 120 caracteres. Dos audiencias pueden compartir nombre, porque una audiencia se referencia por su id.
descriptionString or nil: Texto libre para quien lea la lista más adelante. Es nil cuando nadie escribió nada, y `description: nil` en `update` lo borra.
builtinString or nil: `default` en exactamente una fila por espacio de trabajo, la audiencia que contiene a todos los contactos, y nil en cada audiencia que alguien creó. Compáralo con `"default"` en lugar de comprobar si es nil, para que una audiencia integrada que se añada más tarde no se confunda con la audiencia por defecto.
contactCountInteger: Cuántos contactos hay en la audiencia, contados en el momento de la lectura en lugar de almacenarse en caché. Dos lecturas a uno y otro lado de un `contacts.create` difieren en uno.
lastContactAtString or nil: ISO 8601 UTC, cuándo se unió a esta audiencia el contacto que se unió más recientemente. Es nil mientras la audiencia está vacía.
createdAtString: ISO 8601 UTC, cuándo se creó la audiencia. Determina el orden de la lista después de la audiencia por defecto.
updatedAtString: ISO 8601 UTC, se actualiza al renombrar o al cambiar la descripción. Los cambios de pertenencia no lo tocan.

Parámetros: audiences.list_contacts

limitInteger: Cuántos contactos por página, un número entero de 1 a 200, con 50 por defecto.
cursorString: El `next_cursor` de la página anterior, enviado con los mismos `q:`, `source:`, `sort:` y `statuses:`. Un cursor que nombra un contacto que no está en esta audiencia es un 400 `invalid_cursor`, lanzado como `OpenEmail::InvalidRequestError`.
qString: Busca en el nombre y la dirección, hasta 200 caracteres. Si nada coincide exactamente en la primera página, se devuelven grafías cercanas, y las páginas siguientes siguen buscando del mismo modo.
sourceString: `manual` para los contactos que alguien guardó a propósito, `auto` para los que registró el redactor de la aplicación. Omítelo para todos los de la audiencia.
sortString: `last-heard-newest` (por defecto) y `last-heard-oldest` van por `lastSeenAt`, y los contactos a los que nunca se ha escrito quedan al final en el primero y al principio en el segundo. `added-newest` y `added-oldest` van por cuándo se unió cada contacto a esta audiencia, y `name` ignora mayúsculas y ordena un contacto sin nombre por su dirección.
statusesArray<String>: `["subscribed"]` deja a los miembros que no se han dado de baja y `["unsubscribed"]` a los que sí. Omítelo, pasa un Array vacío o nombra ambos para ver a todos los de la audiencia. `OpenEmail::AUDIENCE_MEMBER_STATUSES` contiene los valores, y la gema los envía unidos con comas como parámetro de consulta `status`.

Respuesta: un contacto en una audiencia

list_contacts devuelve una OpenEmail::Page de Hashes de contacto, y list_all_contacts e iterate_contacts recorren todas las páginas con los mismos argumentos nombrados. Cada fila es un contacto con la forma que devuelve contacts.list, cuyos campos están en la página Contactos, con dos más. Recorrer todas las páginas es la forma de exportar una audiencia.

addedAtString: ISO 8601 UTC, cuándo se unió el contacto a esta audiencia. Sacar un contacto y volver a añadirlo lo pone a cero.
unsubscribedAtString or nil: ISO 8601 UTC, cuándo se dio de baja el contacto de un envío masivo a esta audiencia, o nil mientras está suscrito. Un contacto dado de baja sigue en la audiencia, y los envíos masivos a ella lo omiten. Sacarlo y volver a añadirlo lo deja suscrito de nuevo.

Añadir y quitar en bloque

add_contacts y remove_contacts reciben emails:, un Array de 1 a 200 direcciones, y cambian una audiencia en una sola solicitud. add_contacts nunca crea un contacto. Una dirección que no lo es vuelve en missing, e import_contacts es la llamada que los crea. Ambas se pueden repetir sin riesgo, así que la gema las reintenta tras un fallo de red, y un reintento devuelve a las mismas personas como ya hechas en lugar de fallar.

Añadir a la audiencia por defecto responde added: 0, porque todos los contactos ya están en ella, y remove_contacts sobre ella se rechaza con 409 audience_immutable. Sacar a alguien de una audiencia lo deja en la libreta de direcciones, en la audiencia por defecto y en sus otras audiencias.

audienceIdString: La audiencia que cambió la llamada, en ambos resultados.
addedInteger: En el resultado de `add_contacts`: las pertenencias nuevas que hizo esta llamada.
unchangedInteger: En el resultado de `add_contacts`: contactos que ya estaban en la audiencia. No se escribió nada para ellos.
removedInteger: En el resultado de `remove_contacts`: las pertenencias que quitó esta llamada.
notInAudienceArray<String>: En el resultado de `remove_contacts`: contactos que no estaban en la audiencia, así que no les pasó nada.
missingArray<String>: En ambos: las direcciones que no son contactos en este espacio de trabajo, en minúsculas y sin repeticiones.

Importar

import_contacts es la importación CSV de la página de la audiencia. Recibe contacts:, un Array de 1 a 500 Hashes, cada uno con un email y un name opcional. Cada dirección bien formada se convierte en contacto si aún no lo es, y todas acaban en la audiencia. Envía una lista más larga en varias llamadas. Necesita audiences:write y contacts:write, y una clave a la que le falte alguno se rechaza con 403 insufficient_scope, con scope_missing? a true en el error.

Una dirección que ya es contacto se reutiliza y conserva su nombre, y un name aquí solo rellena uno vacío. Un contacto nuevo se guarda como manual y también se une a la audiencia por defecto, y una dirección que se eliminó de la libreta vuelve. Repetir las mismas filas no crea nada dos veces, así que la gema reintenta la llamada tras un fallo de red.

audienceIdString: La audiencia a la que fueron las filas.
createdInteger: Contactos nuevos que guardó esta llamada.
addedInteger: Membresías nuevas en esta audiencia, contando los contactos que ya existían y aún no estaban en ella.
skippedInteger: Filas que no se importaron porque la dirección estaba mal formada.
invalidArray<String>: Las direcciones mal formadas, tal como se enviaron.

Vaciar

empty(id) saca todos los contactos de una audiencia en una sola solicitud y devuelve la audiencia tal como queda, con contactCount a 0, más removed, el número de pertenencias quitadas. La audiencia conserva su id, su nombre y su descripción, y cada contacto sigue en la libreta de direcciones y en sus otras audiencias.

No se puede deshacer y nada registra quién estaba en la lista, así que recorre list_all_contacts antes si puede que la quieras de vuelta. La audiencia por defecto no se puede vaciar, y la llamada se rechaza con 409 audience_immutable. La gema no reintenta empty tras un fallo de red, porque una segunda llamada tiene éxito con removed: 0. Si se perdió una respuesta, lee la audiencia con get.

Crecimiento

growth lee cuántos contactos se unieron a cada audiencia en un periodo que termina ahora, y cuántos se dieron de baja dentro de él, por día, hora o minuto. Es el gráfico de la página de audiencias. Acepta argumentos nombrados, necesita audiences:read y devuelve 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

Una audiencia registra cuándo alguien se unió y nunca cuándo se fue, así que cada cifra cuenta a las personas que siguen hoy en la lista según la fecha en que se unieron, y una línea nunca baja. Un contacto que se unió y luego se fue no está en ninguna de las cifras.

Parámetros

audience_idsArray<String>: Hasta 50 ids de audiencia, enviados unidos por comas. Omítelo, o pasa un Array vacío, para todas las audiencias. Un id que no es una audiencia de este espacio de trabajo es un 404 `audience_not_found`, y más de 50 es un 422.
daysInteger: Hasta dónde llega el periodo hacia atrás, de 1 a 1095. Es 30 cuando no se da ni `days:` ni `minutes:`.
minutesInteger: El periodo en minutos, de 1 a 1576800, para un periodo de menos de un día. Prevalece sobre `days:` si se dan ambos.
grainString: El tamaño de cada tramo: `day` (por defecto), `hour` o `minute`.
offset_minutesInteger: El desfase de quien mira respecto a UTC en minutos, de -840 a 840, para que los tramos diarios y horarios empiecen en su límite local. 0 por defecto. `Time.now.utc_offset / 60` es el desfase de la máquina en la que se ejecuta el código.

Respuesta

sinceString: ISO 8601 UTC, el inicio del primer tramo.
untilString: ISO 8601 UTC, el momento de la lectura.
totalsHash: `contacts` cuenta a cada persona una vez, esté en las listas que esté, y `memberships` suma las listas, así que una persona cuenta una vez por cada lista leída que la contiene. `added` suma las altas del periodo, `lists` es cuántas audiencias se leyeron, y `busiest` es el tramo con más altas, o nil. `subscribed` cuenta a cada persona que sigue suscrita a al menos una de las audiencias leídas, y `unsubscribed` suma las bajas dentro del periodo.
seriesArray<Hash>: Una entrada por audiencia, de mayor a menor y luego por nombre: `id`, `name`, `builtin`, `total` miembros actuales, `subscribed` (los que siguen suscritos), `before` (los que se unieron antes de `since`), `added` (los que se unieron dentro del periodo), `unsubscribed` (los que se dieron de baja dentro de él) y `buckets`, del más antiguo al más reciente, cada uno un Hash con `bucket`, `added` y `unsubscribed`. Aquí `builtin` es `true` en la audiencia por defecto y `false` en el resto, no la String que lleva el Hash de una audiencia. Solo se listan los tramos con alguna alta o baja, con claves `YYYY-MM-DD`, `YYYY-MM-DDTHH` o `YYYY-MM-DDTHH:MM` en la hora local del desfase.