Kitleler
`audiences.list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `list_contacts`, `add_contact`, `add_contacts`, `import_contacts`, `remove_contact` ve `remove_contacts`.
Her yöntem
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)Bir kitle, bu çalışma alanındaki kişilerin adlandırılmış bir listesidir. Her kişi, var olduğu andan itibaren yerleşik varsayılan kitlededir ve bu satırı adlandıran builtin alanıdır. Geri kalanları oluşturmak, doldurmak ve silmek size kalmıştır. Dallanmayı herkesin değiştirebileceği ada göre değil, builtin alanına göre yapın.
Tek bir kitle üzerindeki bir çağrı, kitlenin kimliğini ilk argüman olarak alır; remove_contact ise adresi ikinci argüman olarak alır. Geri kalan her şey bir Ruby anahtar kelimesidir ve bir istek gövdesi tek bir Hash olarak da geçirilebilir. growth ve list_contacts seçenekleri snake_case'tir (audience_ids:, offset_minutes:), bir gövdenin alanları ise API'nin adlarını korur (emails:, contacts:). Bir yanıt, API'nin camelCase adlarıyla Symbol anahtarlı bir Hash'tir; bu yüzden audience[:contactCount] sayıyı okur.
Bir ya da daha fazla kitleye, Toplu gönderimler sayfasında anlatılan client.broadcasts.send ile gönderin. Bir kişiyi bir kitleye koymak kişiye değil kitleye yapılan bir yazmadır; bu yüzden denetlenen tek kapsam audiences:write'tır. İstisna import_contacts'tır. Kişi oluşturduğu için contacts:write de gerektirir.
add_contact zaten kişi olan bir adresi alır ve kişi olmayanı OpenEmail::ValidationError olarak fırlatılan 422 contact_not_found ile reddeder. Onu önce client.contacts.create ile kaydedin. Birini iki kez eklemek, asıl addedAt değerini taşıyan mevcut üyelikle yanıt verir; bu yüzden çağrıyı yeniden denemek güvenlidir ve gem bir ağ hatasından sonra onu yeniden dener.
Varsayılan kitle diğerleri gibi yeniden adlandırılabilir ve açıklanabilir, ancak silinemez ve içinden kişi çıkarılamaz. İkisi de conflict? değeri true olan bir OpenEmail::ConflictError olarak fırlatılan 409 audience_immutable ile reddedilir. Kişinin gitmesini istiyorsanız kişiyi silin.
Yanıt: bir kitle
list bunlardan bir sayfayı items, has_more? ve next_cursor içeren bir OpenEmail::Page olarak döndürür: önce varsayılan kitle, ardından diğerleri en yeniden eskiye. limit: en fazla 100'e kadar istemedikçe bir sayfa 25 kitle içerir. list_all tüm sayfaları tek bir Array içinde döndürür, iterate ise kitleleri birer birer bir bloğa verir ya da blok olmadan bir Enumerator döndürür. get, create ve update her biri tek bir kitle döndürür. list_contacts ise bunun yerine bir kişi sayfası döndürür: üyelik kayıtları değil, her birinin katıldığı tarihle birlikte kişilerin kendileri; yanında list_all_contacts ve iterate_contacts bulunur.
idString- Kalıcı tanıtıcı: `aud_` ve ardından 24 onaltılık karakter. Adlar benzersiz değildir, bu yüzden saklanan yapılandırmaya girmesi gereken değer budur.
nameString- Yazarken kırpılır, 1 ila 120 karakter. İki kitle aynı adı taşıyabilir, çünkü bir kitleye id'siyle erişilir.
descriptionString or nil- Listeyi daha sonra okuyacak kişi için serbest metin. Kimse bir şey yazmadıysa nil'dir ve `update` üzerinde `description: nil` onu temizler.
builtinString or nil- Her çalışma alanında tam olarak bir satırda, yani her kişiyi içeren kitlede `default`; birinin oluşturduğu her kitlede nil. Daha sonra eklenecek yerleşik bir kitle varsayılan kitleyle karıştırılmasın diye nil olup olmadığını denetlemek yerine `"default"` ile karşılaştırın.
contactCountInteger- Kitledeki kişi sayısı; önbelleğe alınmak yerine okuma anında sayılır. Bir `contacts.create` çağrısının iki yanındaki iki okuma bir fark gösterir.
lastContactAtString or nil- ISO 8601 UTC; en son katılan kişinin bu kitleye katıldığı an. Kitle boşken nil.
createdAtString- ISO 8601 UTC; kitlenin oluşturulduğu an. Varsayılan kitleden sonraki liste sırasını belirler.
updatedAtString- ISO 8601 UTC; yeniden adlandırma ya da açıklama değişikliğiyle güncellenir. Üyelik değişiklikleri ona dokunmaz.
Parametreler: audiences.list_contacts
limitInteger- Sayfa başına kişi sayısı; 1 ile 200 arasında bir tam sayı, varsayılanı 50.
cursorString- Önceki sayfanın `next_cursor` değeri; aynı `q:`, `source:`, `sort:` ve `statuses:` ile gönderilir. Bu kitlede olmayan bir kişiyi belirten bir cursor, `OpenEmail::InvalidRequestError` olarak fırlatılan bir 400 `invalid_cursor` verir.
qString- Adı ve adresi arar, en fazla 200 karakter. İlk sayfada hiçbir şey tam eşleşmezse bunun yerine yakın yazımlar döner ve sonraki sayfalar da aynı şekilde eşleşmeye devam eder.
sourceString- Birinin bilerek kaydettiği kişiler için `manual`, uygulamanın yazma ekranının kaydettikleri için `auto`. Kitledeki herkes için belirtmeyin.
sortString- `last-heard-newest` (varsayılan) ve `last-heard-oldest`, `lastSeenAt` değerine göre sıralar; hiç posta gönderilmemiş kişiler ilkinde en sonda, ikincisinde en başta yer alır. `added-newest` ve `added-oldest` her kişinin bu kitleye katıldığı zamana göre sıralar; `name` ise büyük/küçük harfi yok sayar ve adı olmayan bir kişiyi adresine göre sıralar.
statusesArray<String>- `["subscribed"]` abonelikten çıkmamış üyeleri, `["unsubscribed"]` ise çıkmış olanları tutar. Kitledeki herkes için belirtmeyin, boş bir Array geçirin ya da ikisini birden belirtin. `OpenEmail::AUDIENCE_MEMBER_STATUSES` değerleri tutar ve gem bunları virgülle birleştirerek `status` sorgu parametresi olarak gönderir.
Yanıt: bir kitledeki bir kişi
list_contacts kişi Hash'lerinden oluşan bir OpenEmail::Page döndürür; list_all_contacts ve iterate_contacts aynı anahtar kelimelerle her sayfayı dolaşır. Her satır, alanları Kişiler sayfasında anlatılan contacts.list biçiminde bir kişidir ve iki alan daha içerir. Bir kitleyi dışa aktarmanın yolu her sayfayı dolaşmaktır.
addedAtString- ISO 8601 UTC; kişinin bu kitleye katıldığı an. Bir kişiyi çıkarıp yeniden eklemek bu zamanı sıfırdan başlatır.
unsubscribedAtString or nil- ISO 8601 UTC; kişinin bu kitleye gönderilen bir toplu gönderimden abonelikten çıktığı an; abone olduğu sürece nil. Abonelikten çıkmış bir kişi kitlede kalır ve kitleye yapılan toplu gönderimler onu atlar. Onu çıkarıp yeniden eklemek yeniden abone yapar.
Toplu ekleme ve çıkarma
add_contacts ve remove_contacts, 1 ile 200 arası adresten oluşan bir Array olan emails: alır ve tek bir istekte tek bir kitleyi değiştirir. add_contacts asla kişi oluşturmaz. Kişi olmayan bir adres missing içinde döner; kişileri oluşturan çağrı import_contacts'tır. İkisini de tekrarlamak güvenlidir; bu yüzden gem bir ağ hatasından sonra onları yeniden dener ve bir yeniden deneme başarısız olmak yerine aynı kişileri zaten işlenmiş olarak bildirir.
Varsayılan kitleye ekleme added: 0 ile yanıt verir, çünkü her kişi zaten içindedir; üzerinde remove_contacts ise 409 audience_immutable ile reddedilir. Birini bir kitleden çıkarmak onu adres defterinde, varsayılan kitlede ve diğer kitlelerinde bırakır.
audienceIdString- Çağrının değiştirdiği kitle, iki sonuçta da.
addedInteger- `add_contacts` sonucunda: bu çağrının oluşturduğu yeni üyelikler.
unchangedInteger- `add_contacts` sonucunda: zaten kitlede olan kişiler. Onlar için hiçbir şey yazılmadı.
removedInteger- `remove_contacts` sonucunda: bu çağrının kaldırdığı üyelikler.
notInAudienceArray<String>- `remove_contacts` sonucunda: kitlede olmayan, bu yüzden başlarına hiçbir şey gelmeyen kişiler.
missingArray<String>- İkisinde de: bu çalışma alanında kişi olmayan adresler, küçük harfle ve tekrarsız.
İçe aktarma
import_contacts, kitle sayfasındaki CSV içe aktarmasıdır. Her biri bir email ve isteğe bağlı bir name içeren 1 ile 500 arası Hash'ten oluşan bir Array olan contacts: alır. Doğru biçimlendirilmiş her adres henüz kişi değilse kişi olur ve hepsi kitleye düşer. Daha uzun bir listeyi birkaç çağrıda gönderin. audiences:write ve contacts:write gerektirir; ikisinden birine sahip olmayan bir anahtar, hata üzerinde scope_missing? değeri true olan 403 insufficient_scope ile reddedilir.
Zaten kişi olan bir adres yeniden kullanılır ve adını korur; buradaki bir name yalnızca boş olan bir adı doldurur. Yeni bir kişi manual olarak kaydedilir ve varsayılan kitleye de katılır; defterden silinmiş bir adres ise geri gelir. Aynı satırları yeniden göndermek hiçbir şeyi iki kez oluşturmaz; bu yüzden gem bir ağ hatasından sonra çağrıyı yeniden dener.
audienceIdString- Satırların girdiği kitle.
createdInteger- Bu çağrının kaydettiği yeni kişiler.
addedInteger- Bu kitledeki yeni üyelikler; zaten var olan ve henüz kitlede olmayan kişiler de sayılır.
skippedInteger- Adres hatalı biçimli olduğu için içe aktarılmayan satırlar.
invalidArray<String>- Hatalı biçimli adresler, tam gönderildikleri gibi.
Boşaltma
empty(id) tek bir istekte bir kitledeki tüm kişileri çıkarır ve kitleyi şu anki hâliyle, contactCount değeri 0 olarak ve kaldırılan üyelik sayısı olan removed ile birlikte döndürür. Kitle kimliğini, adını ve açıklamasını korur; her kişi de adres defterinde ve diğer kitlelerinde kalır.
Geri alınamaz ve listede kimlerin olduğu hiçbir yere kaydedilmez; bu yüzden listeyi geri isteyebilecekseniz önce list_all_contacts ile dolaşın. Varsayılan kitle boşaltılamaz ve çağrı 409 audience_immutable ile reddedilir. Gem bir ağ hatasından sonra empty çağrısını yeniden denemez, çünkü ikinci bir çağrı removed: 0 ile başarılı olur. Bir yanıt kaybolduysa kitleyi get ile okuyun.
Büyüme
growth, şu anda biten bir pencere boyunca her kitleye kaç kişinin katıldığını ve bu pencerede kaçının abonelikten çıktığını gün, saat ya da dakikaya göre okur. Kitleler sayfasındaki grafik budur. Anahtar kelimeler alır, audiences:read gerektirir ve tek bir Hash döndürür.
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"endBir kitle birinin ne zaman katıldığını kaydeder, ne zaman ayrıldığını asla kaydetmez; bu yüzden her sayı bugün hâlâ listede olan kişileri katılım tarihlerine göre sayar ve bir çizgi hiçbir zaman düşmez. Katılıp sonra ayrılan bir kişi sayıların hiçbirinde yer almaz.
Parametreler
audience_idsArray<String>- Virgülle birleştirilerek gönderilen en fazla 50 kitle kimliği. Tüm kitleler için belirtmeyin ya da boş bir Array geçirin. Bu çalışma alanında bir kitle olmayan bir kimlik 404 `audience_not_found`, 50'den fazlası ise 422 verir.
daysInteger- Pencerenin geriye ne kadar uzandığı; 1 ile 1095 arası. Ne `days:` ne de `minutes:` verilmediğinde 30'dur.
minutesInteger- Bir günden kısa bir pencere için dakika cinsinden pencere; 1 ile 1576800 arası. İkisi de verildiğinde `days:` değerine üstün gelir.
grainString- Her dilimin boyutu: `day` (varsayılan), `hour` veya `minute`.
offset_minutesInteger- Görüntüleyenin UTC'ye göre dakika cinsinden ofseti; -840 ile 840 arası, böylece gün ve saat aralıkları yerel sınırlarında başlar. Varsayılan olarak 0. `Time.now.utc_offset / 60`, kodun çalıştığı makinenin ofsetidir.
Yanıt
sinceString- ISO 8601 UTC; ilk aralığın başlangıcı.
untilString- ISO 8601 UTC; okumanın yapıldığı an.
totalsHash- `contacts` her kişiyi kaç listede olursa olsun bir kez sayar; `memberships` ise listeleri toplar, bu yüzden bir kişi onu içeren okunan her liste için bir kez sayılır. `added` penceredeki katılımları toplar, `lists` kaç kitlenin okunduğunu gösterir, `busiest` ise en çok katılımın olduğu aralıktır ya da nil'dir. `subscribed`, okunan kitlelerden en az birine hâlâ abone olan her kişiyi sayar; `unsubscribed` ise pencere içindeki abonelikten çıkmaları toplar.
seriesArray<Hash>- Her kitle için bir kayıt; önce en büyükler, sonra ada göre: `id`, `name`, `builtin`, şu anki üye sayısı olan `total`, `subscribed` (hâlâ abone olanlar), `before` (`since` öncesinde katılanlar), `added` (pencere içinde katılanlar), `unsubscribed` (pencere içinde abonelikten çıkanlar) ve en eskiden başlayarak her biri `bucket`, `added` ve `unsubscribed` içeren bir Hash olan `buckets`. Burada `builtin`, bir kitle Hash'inin taşıdığı String değil; varsayılan kitlede `true`, diğerlerinde `false` olur. Yalnızca bir katılım ya da abonelikten çıkma içeren aralıklar listelenir; anahtarları ofsetin yerel saatine göre `YYYY-MM-DD`, `YYYY-MM-DDTHH` ya da `YYYY-MM-DDTHH:MM` biçimindedir.