Ruby

ऑडियंस

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

हर मेथड

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)

ऑडियंस इस वर्कस्पेस में संपर्कों की एक नामित सूची है। हर संपर्क बनते ही built-in डिफ़ॉल्ट ऑडियंस में होता है, और builtin ही उस पंक्ति की पहचान बताता है। बाक़ी आप ख़ुद बनाते, भरते और हटाते हैं। शाखा नाम पर नहीं, builtin पर बनाएँ, क्योंकि नाम कोई भी बदल सकता है।

किसी एक ऑडियंस पर कॉल उसकी id को पहले argument के रूप में लेती है, और remove_contact पते को दूसरे के रूप में लेता है। बाक़ी सब Ruby keyword है, और रिक्वेस्ट बॉडी एक Hash के रूप में भी पास की जा सकती है। growth और list_contacts के विकल्प snake_case में हैं (audience_ids:, offset_minutes:), जबकि बॉडी के फ़ील्ड API के नाम बनाए रखते हैं (emails:, contacts:)। जवाब API के camelCase में Symbol कुंजियों वाला Hash है, इसलिए audience[:contactCount] गिनती पढ़ता है।

एक या अधिक ऑडियंस को client.broadcasts.send से भेजें, जो “ब्रॉडकास्ट” पेज पर है। किसी संपर्क को ऑडियंस में डालना संपर्क पर नहीं, ऑडियंस पर write है, इसलिए सिर्फ़ audiences:write scope जाँचा जाता है। import_contacts अपवाद है। यह संपर्क बनाता है, इसलिए इसे contacts:write भी चाहिए।

add_contact ऐसा पता लेता है जो पहले से संपर्क है और जो नहीं है उसे 422 contact_not_found के साथ अस्वीकार करता है, जो OpenEmail::ValidationError के रूप में raise होता है। पहले उसे client.contacts.create से सहेजें। किसी को दो बार जोड़ने पर पहले से मौजूद सदस्यता के साथ जवाब आता है, उसके मूल addedAt के साथ, इसलिए इस कॉल पर पुनः प्रयास सुरक्षित है, और gem नेटवर्क विफलता के बाद इस पर पुनः प्रयास करता है।

डिफ़ॉल्ट ऑडियंस का नाम और विवरण किसी भी दूसरी की तरह बदला जा सकता है, पर उसे न हटाया जा सकता है न घटाया। दोनों 409 audience_immutable के साथ अस्वीकार होते हैं, जो conflict? true वाले OpenEmail::ConflictError के रूप में raise होता है। जब आप चाहते हों कि संपर्क ही चला जाए तो संपर्क को हटाएँ।

जवाब: एक ऑडियंस

list इनका एक पेज items, has_more? और next_cursor वाले OpenEmail::Page के रूप में लौटाता है, डिफ़ॉल्ट ऑडियंस पहले और बाक़ी सबसे नई पहले। एक पेज में 25 होती हैं, जब तक limit: 100 तक न माँगे। list_all हर पेज एक Array में लौटाता है, और iterate एक बार में एक ऑडियंस block में yield करता है, या block के बिना एक Enumerator लौटाता है। get, create और update हर एक एक ऑडियंस लौटाते हैं। list_contacts इसकी जगह संपर्कों का पेज लौटाता है, सदस्यता रिकॉर्ड नहीं बल्कि ख़ुद संपर्क, हर एक के जुड़ने की तारीख़ के साथ, और उसके साथ list_all_contacts तथा iterate_contacts हैं।

idString: टिकाऊ हैंडल, `aud_` के बाद 24 hex अक्षर। नाम अद्वितीय नहीं होते, इसलिए संग्रहीत कॉन्फ़िगरेशन में यही रखना चाहिए।
nameString: लिखते समय trim किया जाता है, 1 से 120 अक्षर। दो ऑडियंस एक ही नाम रख सकती हैं, क्योंकि ऑडियंस को उसके id से संबोधित किया जाता है।
descriptionString or nil: जो भी बाद में सूची पढ़े उसके लिए मुक्त टेक्स्ट। जब किसी ने कुछ न लिखा हो तो nil, और `update` पर `description: nil` इसे साफ़ कर देता है।
builtinString or nil: हर वर्कस्पेस में ठीक एक पंक्ति पर `default`, वह ऑडियंस जिसमें हर संपर्क होता है, और किसी की बनाई हर ऑडियंस पर nil। nil जाँचने के बजाय इसकी तुलना `"default"` से करें, ताकि बाद में जोड़ी गई कोई built-in ऑडियंस डिफ़ॉल्ट ऑडियंस न समझ ली जाए।
contactCountInteger: ऑडियंस में कितने contacts हैं, जो कैश से नहीं बल्कि पढ़ने के क्षण गिने जाते हैं। `contacts.create` के दोनों ओर किए गए दो पाठ एक से अलग होंगे।
lastContactAtString or nil: ISO 8601 UTC, जब सबसे हाल में जुड़ा संपर्क इस ऑडियंस में जुड़ा। जब तक ऑडियंस ख़ाली है तब तक nil।
createdAtString: ISO 8601 UTC, जब ऑडियंस बनी। डिफ़ॉल्ट के बाद सूची का क्रम यही तय करता है।
updatedAtString: ISO 8601 UTC, नाम या विवरण बदलने पर आगे बढ़ता है। सदस्यता के बदलाव इसे नहीं छूते।

पैरामीटर: audiences.list_contacts

limitInteger: हर पेज पर कितने संपर्क, 1 से 200 तक की पूर्ण संख्या, डिफ़ॉल्ट 50।
cursorString: पिछले पेज का `next_cursor`, उन्हीं `q:`, `source:`, `sort:` और `statuses:` के साथ भेजा गया। जो cursor ऐसे संपर्क का नाम लेता है जो इस ऑडियंस में नहीं है, वह 400 `invalid_cursor` है, जो `OpenEmail::InvalidRequestError` के रूप में raise होता है।
qString: नाम और पते में खोजता है, 200 अक्षरों तक। अगर पहले पेज पर कुछ भी ठीक-ठीक मेल न खाए, तो उसकी जगह मिलती-जुलती वर्तनियाँ लौटती हैं, और आगे के पेज उसी तरह मिलान करते रहते हैं।
sourceString: जानबूझकर सहेजे गए संपर्कों के लिए `manual`, ऐप के composer द्वारा दर्ज संपर्कों के लिए `auto`। ऑडियंस के सभी लोगों के लिए इसे छोड़ दें।
sortString: `last-heard-newest` (डिफ़ॉल्ट) और `last-heard-oldest` `lastSeenAt` के हिसाब से चलते हैं, और जिन संपर्कों को कभी मेल नहीं भेजा गया वे पहले में आख़िर में और दूसरे में पहले आते हैं। `added-newest` और `added-oldest` इस हिसाब से चलते हैं कि हर संपर्क इस ऑडियंस में कब जुड़ा, और `name` case को अनदेखा करता है और बिना नाम वाले संपर्क को उसके पते से क्रमित करता है।
statusesArray<String>: `["subscribed"]` उन सदस्यों को रखता है जिन्होंने सदस्यता नहीं छोड़ी और `["unsubscribed"]` उन्हें जिन्होंने छोड़ी। ऑडियंस के सभी लोगों के लिए इसे छोड़ दें, ख़ाली Array पास करें, या दोनों के नाम दें। `OpenEmail::AUDIENCE_MEMBER_STATUSES` में ये मान हैं, और gem इन्हें कॉमा से जोड़कर `status` query पैरामीटर के रूप में भेजता है।

जवाब: किसी ऑडियंस में एक संपर्क

list_contacts संपर्क Hashes का एक OpenEmail::Page लौटाता है, और list_all_contacts तथा iterate_contacts उन्हीं keywords के साथ हर पेज पर चलते हैं। हर पंक्ति उसी आकार का संपर्क है जो contacts.list लौटाता है, जिसके फ़ील्ड “संपर्क” पेज पर हैं, और दो फ़ील्ड ज़्यादा। हर पेज पर चलना ही किसी ऑडियंस को export करने का तरीका है।

addedAtString: ISO 8601 UTC, जब संपर्क इस ऑडियंस में जुड़ा। किसी संपर्क को निकालकर फिर जोड़ने से यह नए सिरे से शुरू होता है।
unsubscribedAtString or nil: ISO 8601 UTC, जब संपर्क ने इस ऑडियंस को भेजे गए किसी ब्रॉडकास्ट से सदस्यता छोड़ी, या जब तक वह सदस्य है तब तक nil। सदस्यता छोड़ चुका संपर्क ऑडियंस में बना रहता है, और उसे भेजे जाने वाले ब्रॉडकास्ट उसे छोड़ देते हैं। उसे निकालकर फिर जोड़ने से वह नए सिरे से सदस्य बन जाता है।

एक साथ कई जोड़ना और हटाना

add_contacts और remove_contacts emails: लेते हैं, 1 से 200 पतों की एक Array, और एक रिक्वेस्ट में एक ऑडियंस बदलते हैं। add_contacts कभी संपर्क नहीं बनाता। जो पता संपर्क नहीं है वह missing में लौटता है, और उन्हें बनाने वाली कॉल import_contacts है। दोनों को दोहराना सुरक्षित है, इसलिए gem नेटवर्क विफलता के बाद उन पर पुनः प्रयास करता है, और पुनः प्रयास विफल होने के बजाय उन्हीं लोगों को पहले से हो चुका बताता है।

डिफ़ॉल्ट ऑडियंस में जोड़ने पर जवाब added: 0 आता है, क्योंकि हर संपर्क उसमें पहले से है, और उस पर remove_contacts 409 audience_immutable के साथ अस्वीकार होता है। किसी को ऑडियंस से निकालने पर वह पता-पुस्तिका में, डिफ़ॉल्ट ऑडियंस में और अपनी दूसरी ऑडियंस में बना रहता है।

audienceIdString: वह ऑडियंस जिसे कॉल ने बदला, दोनों नतीजों में।
addedInteger: `add_contacts` के नतीजे पर: इस कॉल से बनी नई सदस्यताएँ।
unchangedInteger: `add_contacts` के नतीजे पर: वे संपर्क जो पहले से ऑडियंस में थे। उनके लिए कुछ नहीं लिखा गया।
removedInteger: `remove_contacts` के नतीजे पर: इस कॉल से हटाई गई सदस्यताएँ।
notInAudienceArray<String>: `remove_contacts` के नतीजे पर: वे संपर्क जो ऑडियंस में नहीं थे, इसलिए उनके साथ कुछ नहीं हुआ।
missingArray<String>: दोनों पर: वे पते जो इस वर्कस्पेस में संपर्क नहीं हैं, छोटे अक्षरों में और बिना दोहराव के।

इम्पोर्ट करना

import_contacts ऑडियंस पेज वाला CSV import है। यह contacts: लेता है, 1 से 500 Hashes की एक Array, हर एक में एक email और वैकल्पिक name। हर सही बना पता, अगर अभी संपर्क नहीं है तो संपर्क बन जाता है, और हर एक ऑडियंस में पहुँचता है। लंबी सूची कई कॉल में भेजें। इसे audiences:write और contacts:write चाहिए, और जिस कुंजी में इनमें से कोई न हो उसे 403 insufficient_scope के साथ अस्वीकार किया जाता है, जहाँ error पर scope_missing? true होता है।

जो पता पहले से संपर्क है वह दोबारा इस्तेमाल होता है और अपना नाम बनाए रखता है, और यहाँ का name सिर्फ़ ख़ाली नाम भरता है। नया संपर्क manual के रूप में सहेजा जाता है और डिफ़ॉल्ट ऑडियंस में भी जुड़ता है, और पुस्तिका से हटाया गया पता वापस आ जाता है। वही पंक्तियाँ दोबारा भेजने से कुछ भी दो बार नहीं बनता, इसलिए gem नेटवर्क विफलता के बाद इस कॉल पर पुनः प्रयास करता है।

audienceIdString: वह ऑडियंस जिसमें पंक्तियाँ गईं।
createdInteger: इस कॉल से सहेजे गए नए संपर्क।
addedInteger: इस ऑडियंस में नई सदस्यताएँ, उन संपर्कों सहित जो पहले से मौजूद थे और अभी इसमें नहीं थे।
skippedInteger: वे पंक्तियाँ जो पता ग़लत बना होने के कारण इम्पोर्ट नहीं हुईं।
invalidArray<String>: ग़लत बने पते, ठीक वैसे ही जैसे वे भेजे गए।

खाली करना

empty(id) एक रिक्वेस्ट में एक ऑडियंस से हर संपर्क निकाल देता है और ऑडियंस को उसकी मौजूदा स्थिति में लौटाता है, contactCount 0 के साथ, साथ में removed, यानी हटाई गई सदस्यताओं की संख्या। ऑडियंस अपनी id, नाम और विवरण बनाए रखती है, और हर संपर्क पता-पुस्तिका में और अपनी दूसरी ऑडियंस में बना रहता है।

इसे पलटा नहीं जा सकता और कुछ भी दर्ज नहीं करता कि सूची में कौन था, इसलिए अगर आपको यह वापस चाहिए हो सकती है तो पहले list_all_contacts पर चलें। डिफ़ॉल्ट ऑडियंस ख़ाली नहीं की जा सकती, और कॉल 409 audience_immutable के साथ अस्वीकार होती है। gem नेटवर्क विफलता के बाद empty पर पुनः प्रयास नहीं करता, क्योंकि दूसरी कॉल removed: 0 के साथ सफल हो जाती है। अगर कोई जवाब खो गया हो तो ऑडियंस को get से पढ़ें।

वृद्धि

growth पढ़ता है कि अभी ख़त्म होने वाली विंडो में हर ऑडियंस में कितने संपर्क जुड़े, और उसके भीतर कितनों ने सदस्यता छोड़ी, दिन, घंटे या मिनट के हिसाब से। यह ऑडियंस पेज वाला चार्ट है। यह keywords लेता है, इसे audiences:read चाहिए और यह एक 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

ऑडियंस दर्ज करती है कि कोई कब जुड़ा, यह कभी नहीं कि कब गया, इसलिए हर संख्या उन लोगों को गिनती है जो आज भी सूची में हैं, उनके जुड़ने की तारीख़ के हिसाब से, और कोई रेखा कभी नीचे नहीं जाती। जो संपर्क जुड़ा और बाद में चला गया वह किसी संख्या में नहीं है।

पैरामीटर

audience_idsArray<String>: 50 तक ऑडियंस ids, कॉमा से जोड़कर भेजी जाती हैं। हर ऑडियंस के लिए इसे छोड़ दें, या ख़ाली Array पास करें। जो id इस वर्कस्पेस की ऑडियंस नहीं है वह 404 `audience_not_found` है, और 50 से ज़्यादा 422 है।
daysInteger: विंडो कितनी पीछे जाती है, 1 से 1095। जब न `days:` दिया हो न `minutes:`, तो यह 30 होता है।
minutesInteger: मिनटों में विंडो, 1 से 1576800, एक दिन से छोटी विंडो के लिए। दोनों दिए हों तो यह `days:` पर भारी पड़ता है।
grainString: हर बकेट का आकार: `day` (डिफ़ॉल्ट), `hour` या `minute`।
offset_minutesInteger: देखने वाले का UTC से अंतर मिनटों में, -840 से 840, ताकि दिन और घंटे के बकेट उनकी स्थानीय सीमा पर शुरू हों। डिफ़ॉल्ट रूप से 0। `Time.now.utc_offset / 60` उस मशीन का offset है जिस पर कोड चलता है।

प्रतिक्रिया

sinceString: ISO 8601 UTC, पहले बकेट की शुरुआत।
untilString: ISO 8601 UTC, पढ़ने का क्षण।
totalsHash: `contacts` हर व्यक्ति को एक बार गिनता है, चाहे वह कितनी भी सूचियों में हो, और `memberships` सूचियों को जोड़ता है, इसलिए कोई व्यक्ति हर उस पढ़ी गई सूची के लिए एक बार गिना जाता है जिसमें वह है। `added` विंडो में हुए जुड़ाव जोड़ता है, `lists` बताता है कि कितनी ऑडियंस पढ़ी गईं, और `busiest` सबसे ज़्यादा जुड़ाव वाला बकेट है, या nil। `subscribed` हर उस व्यक्ति को गिनता है जो पढ़ी गई ऑडियंस में से कम से कम एक में अब भी सदस्य है, और `unsubscribed` विंडो के भीतर सदस्यता छोड़ने वालों को जोड़ता है।
seriesArray<Hash>: हर ऑडियंस के लिए एक प्रविष्टि, सबसे बड़ी पहले और फिर नाम के क्रम में: `id`, `name`, `builtin`, अभी के `total` सदस्य, `subscribed` (जो अब भी सदस्य हैं), `before` (जो `since` से पहले जुड़े), `added` (जो विंडो के भीतर जुड़े), `unsubscribed` (जिन्होंने उसके भीतर सदस्यता छोड़ी) और `buckets`, सबसे पुराना पहले, हर एक `bucket`, `added` और `unsubscribed` वाला Hash। यहाँ `builtin` डिफ़ॉल्ट ऑडियंस पर `true` और बाक़ी पर `false` है, न कि वह String जो ऑडियंस Hash में होती है। सिर्फ़ वे बकेट सूचीबद्ध होते हैं जिनमें कोई जुड़ाव या सदस्यता छोड़ना हुआ, `YYYY-MM-DD`, `YYYY-MM-DDTHH` या `YYYY-MM-DDTHH:MM` कुंजी के साथ, offset के स्थानीय समय में।