PHP

ऑडियंस

`audiences->list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `listContacts`, `addContact`, `addContacts`, `importContacts`, `removeContact` और `removeContacts`।

हर मेथड

audiences.php

$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;

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

किसी एक ऑडियंस पर कॉल उसकी id को पहले आर्ग्युमेंट के रूप में लेती है, और removeContact पते को दूसरे आर्ग्युमेंट के रूप में लेता है। फ़िल्टर और options camelCase में named आर्ग्युमेंट हैं (audienceIds:, offsetMinutes:), जबकि रिक्वेस्ट बॉडी एक array है जिसकी कुंजियाँ API के नाम रखती हैं (emails, contacts)। जवाब API के camelCase वाली कुंजियों का array है, इसलिए $audience['contactCount'] संख्या पढ़ता है।

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

addContact ऐसा पता लेता है जो पहले से संपर्क है और जो नहीं है उसे 422 contact_not_found के साथ अस्वीकार करता है, जो ValidationException के रूप में throw होता है। पहले उसे $client->contacts->create से सहेजें। किसी को दो बार जोड़ने पर पहले से मौजूद सदस्यता लौटती है, उसके मूल addedAt के साथ, इसलिए कॉल को retry करना सुरक्षित है, और क्लाइंट नेटवर्क विफलता के बाद इसे retry करता है।

डिफ़ॉल्ट ऑडियंस का नाम और विवरण किसी भी दूसरी ऑडियंस की तरह बदला जा सकता है, पर उसे न हटाया जा सकता है न छोटा किया जा सकता है। दोनों 409 audience_immutable के साथ अस्वीकार किए जाते हैं, जो isConflict() true वाले ConflictException के रूप में throw होता है। जब आप संपर्क को ही हटाना चाहें तो संपर्क को हटाएँ।

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

list इनका एक पेज items, hasMore और nextCursor वाले OpenEmail\Result\Page के रूप में लौटाता है, पहले डिफ़ॉल्ट ऑडियंस और बाकी सबसे नई पहले। एक पेज में 25 होती हैं, जब तक limit: 100 तक न माँगे। listAll हर ऑडियंस एक array में लौटाता है, और iterate एक Generator लौटाता है जो एक बार में एक ऑडियंस yield करता है। get, create और update में से हर एक, एक ऑडियंस लौटाता है। listContacts इसके बजाय संपर्कों का एक पेज लौटाता है, सदस्यता रिकॉर्ड नहीं बल्कि ख़ुद संपर्क, हर एक के जुड़ने की तारीख़ के साथ, और इसके साथ listAllContacts और iterateContacts हैं।

idstring: टिकाऊ हैंडल, `aud_` के बाद 24 hex अक्षर। नाम अद्वितीय नहीं होते, इसलिए संग्रहीत कॉन्फ़िगरेशन में यही रखना चाहिए।
namestring: लिखते समय trim किया जाता है, 1 से 120 अक्षर। दो ऑडियंस एक ही नाम रख सकती हैं, क्योंकि ऑडियंस को उसके id से संबोधित किया जाता है।
descriptionstring or null: सूची को बाद में पढ़ने वाले के लिए मुक्त text। जब किसी ने कुछ नहीं लिखा हो तो यह null है, और `update` पर `'description' => null` इसे हटा देता है।
builtinstring or null: हर वर्कस्पेस में ठीक एक पंक्ति पर `default`, यानी वह ऑडियंस जिसमें हर संपर्क होता है, और किसी द्वारा बनाई गई हर ऑडियंस पर null। null की जाँच करने के बजाय `'default'` से तुलना करें, ताकि बाद में जोड़ी गई कोई built-in ऑडियंस डिफ़ॉल्ट ऑडियंस न समझ ली जाए।
contactCountint: ऑडियंस में कितने contacts हैं, जो कैश से नहीं बल्कि पढ़ने के क्षण गिने जाते हैं। `contacts->create` के दोनों ओर किए गए दो पाठ एक से अलग होंगे।
lastContactAtstring or null: ISO 8601 UTC, जब सबसे हाल में जुड़ा संपर्क इस ऑडियंस में जुड़ा। जब तक ऑडियंस ख़ाली है तब तक यह null है।
createdAtstring: ISO 8601 UTC, जब ऑडियंस बनी। डिफ़ॉल्ट के बाद सूची का क्रम यही तय करता है।
updatedAtstring: ISO 8601 UTC, नाम या विवरण बदलने पर आगे बढ़ता है। सदस्यता के बदलाव इसे नहीं छूते।

पैरामीटर: audiences->listContacts

limitint: हर पेज पर कितने संपर्क, 1 से 200 तक की पूर्ण संख्या, डिफ़ॉल्ट 50।
cursorstring: पिछले पेज का `nextCursor`, उन्हीं `q:`, `source:`, `sort:` और `statuses:` के साथ भेजा गया। ऐसा cursor जो किसी ऐसे संपर्क का नाम ले जो इस ऑडियंस में नहीं है, 400 `invalid_cursor` है, जो `InvalidRequestException` के रूप में throw होता है।
qstring: नाम और पते में खोजता है, 200 अक्षरों तक। अगर पहले पेज पर कुछ भी ठीक-ठीक मेल न खाए, तो उसकी जगह मिलती-जुलती वर्तनियाँ लौटती हैं, और आगे के पेज उसी तरह मिलान करते रहते हैं।
sourcestring: जानबूझकर सहेजे गए संपर्कों के लिए `manual`, ऐप के composer द्वारा दर्ज संपर्कों के लिए `auto`। ऑडियंस के सभी लोगों के लिए इसे छोड़ दें।
sortstring: `last-heard-newest` (डिफ़ॉल्ट) और `last-heard-oldest` `lastSeenAt` के हिसाब से चलते हैं, और जिन संपर्कों को कभी मेल नहीं भेजा गया वे पहले में आख़िर में और दूसरे में पहले आते हैं। `added-newest` और `added-oldest` इस हिसाब से चलते हैं कि हर संपर्क इस ऑडियंस में कब जुड़ा, और `name` case को अनदेखा करता है और बिना नाम वाले संपर्क को उसके पते से क्रमित करता है।
statusesstring or array: `['subscribed']` उन सदस्यों को रखता है जिन्होंने सदस्यता नहीं छोड़ी और `['unsubscribed']` उन्हें जिन्होंने छोड़ी। ऑडियंस के सभी लोगों के लिए इसे छोड़ दें, ख़ाली array पास करें, या दोनों के नाम दें। `OpenEmail\Constants\AudienceMemberStatuses` इन मानों को रखता है, और क्लाइंट उन्हें कॉमा से जोड़कर `status` query पैरामीटर के रूप में भेजता है।

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

listContacts संपर्क arrays का एक OpenEmail\Result\Page लौटाता है, और listAllContacts और iterateContacts उन्हीं named आर्ग्युमेंट के साथ हर पेज पर चलते हैं। हर पंक्ति उसी आकार का एक संपर्क है जो contacts->list लौटाता है, जिसके फ़ील्ड संपर्क वाले पेज पर हैं, और साथ में दो और। हर पेज पर चलना ही किसी ऑडियंस को export करने का तरीक़ा है।

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

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

addContacts और removeContacts ऐसा array लेते हैं जिसका emails 1 से 200 पतों की सूची हो, और एक रिक्वेस्ट में एक ऑडियंस बदलते हैं। addContacts कभी संपर्क नहीं बनाता। जो पता संपर्क नहीं है वह missing में लौटता है, और उन्हें बनाने वाली कॉल importContacts है। दोनों को दोहराना सुरक्षित है, इसलिए क्लाइंट नेटवर्क विफलता के बाद उन्हें retry करता है, और retry विफल होने के बजाय उन्हीं लोगों को पहले से हो चुका बताता है।

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

audienceIdstring: वह ऑडियंस जिसे कॉल ने बदला, दोनों नतीजों में।
addedint: `addContacts` के नतीजे पर: इस कॉल से बनी नई सदस्यताएँ।
unchangedint: `addContacts` के नतीजे पर: वे संपर्क जो पहले से ऑडियंस में थे। उनके लिए कुछ नहीं लिखा गया।
removedint: `removeContacts` के नतीजे पर: इस कॉल से हटाई गई सदस्यताएँ।
notInAudiencearray: `removeContacts` के नतीजे पर: वे संपर्क जो ऑडियंस में नहीं थे, इसलिए उनके साथ कुछ नहीं हुआ।
missingarray: दोनों पर: वे पते जो इस वर्कस्पेस में संपर्क नहीं हैं, छोटे अक्षरों में और बिना दोहराव के।

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

importContacts ऑडियंस पेज वाला CSV import है। यह ऐसा array लेता है जिसका contacts 1 से 500 arrays की सूची हो, हर एक में एक email और वैकल्पिक name। हर सही रूप वाला पता, अगर अभी संपर्क नहीं है तो संपर्क बन जाता है, और हर एक ऑडियंस में पहुँच जाता है। लंबी सूची कई कॉल में भेजें। इसे audiences:write और contacts:write चाहिए, और जिस कुंजी में इनमें से कोई न हो वह 403 insufficient_scope के साथ अस्वीकार होती है, जिसके exception पर isScopeMissing() true होता है।

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

audienceIdstring: वह ऑडियंस जिसमें पंक्तियाँ गईं।
createdint: इस कॉल से सहेजे गए नए संपर्क।
addedint: इस ऑडियंस में नई सदस्यताएँ, उन संपर्कों सहित जो पहले से मौजूद थे और अभी इसमें नहीं थे।
skippedint: वे पंक्तियाँ जो पता ग़लत बना होने के कारण इम्पोर्ट नहीं हुईं।
invalidarray: ग़लत बने पते, ठीक वैसे ही जैसे वे भेजे गए।

खाली करना

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

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

वृद्धि

growth पढ़ता है कि अभी ख़त्म होने वाली अवधि में हर ऑडियंस में कितने संपर्क जुड़े, और उस अवधि में कितनों ने सदस्यता छोड़ी, दिन, घंटे या मिनट के हिसाब से। यह ऑडियंस पेज वाला चार्ट है। यह named आर्ग्युमेंट लेता है, इसे audiences:read चाहिए और यह एक array लौटाता है।

audience_growth.php

$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;}

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

पैरामीटर

audienceIdsstring or array: अधिकतम 50 ऑडियंस id, सूची या कॉमा से अलग की गई एक स्ट्रिंग के रूप में, कॉमा से जोड़कर भेजी जाती हैं। हर ऑडियंस के लिए इसे छोड़ दें, या ख़ाली array पास करें। ऐसी id जो इस वर्कस्पेस की ऑडियंस नहीं है, 404 `audience_not_found` है, और 50 से ज़्यादा होने पर 422।
daysint: विंडो कितनी पीछे जाती है, 1 से 1095। जब न `days:` दिया हो न `minutes:`, तो यह 30 होता है।
minutesint: मिनटों में विंडो, 1 से 1576800, एक दिन से छोटी विंडो के लिए। दोनों दिए हों तो यह `days:` पर भारी पड़ता है।
grainstring: हर बकेट का आकार: `day` (डिफ़ॉल्ट), `hour` या `minute`।
offsetMinutesint: देखने वाले का UTC से offset, मिनटों में, -840 से 840, ताकि दिन और घंटे के bucket अपनी स्थानीय सीमा पर शुरू हों। डिफ़ॉल्ट रूप से 0। `intdiv((int) date('Z'), 60)` उस zone का offset है जिस पर PHP सेट है।

प्रतिक्रिया

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