النماذج
`forms.list` و`get` و`create` و`update` و`delete` و`publish` و`pause` و`resume` و`duplicate` و`analytics` و`list_starters` و`get_starter` و`list_submissions` و`get_submission` و`delete_submission` و`delete_submissions` و`approve_submission` و`resend_confirmation` و`subscribe`.
كل الدوالّ
form = client.forms.create( name: "Newsletter sign-up", starter: "newsletter", settings: {audienceIds: ["aud_4c1b8e2a7d9f05c36b4e8a71"]}, publish: true) puts form[:url], form[:subscribeUrl] saved = client.forms.update( form[:id], settings: {doubleOptIn: true, senderAddress: "[email protected]"}, expectedUpdatedAt: form[:updatedAt]) signup = client.forms.subscribe(form[:id], email: "[email protected]", first_name: "Ann", consent: true) client.forms.iterate_submissions(form[:id], status: "pending") do |submission| client.forms.resend_confirmation(form[:id], submission[:id]) if submission[:expired]end stats = client.forms.analytics(form[:id], days: 30)starters = client.forms.list_starters client.forms.pause(form[:id])client.forms.resume(form[:id])copy = client.forms.duplicate(form[:id])client.forms.delete(copy[:id]) puts saved[:senderIssue], signup[:outcome], stats.dig(:totals, :conversion), starters.sizeيحتفظ النموذج بمسودة document وبـ publishedDocument الذي يراه الزوار. ويغيّر update المسودة والإعدادات، وينشر publish المسودة. وتسري الإعدادات فورًا، سواء نُشر النموذج أم لا، ويرفض expectedUpdatedAt بالخطأ 409 version_conflict، المرفوع في صورة OpenEmail::ConflictError، أي حفظ قد يكتب فوق حفظ شخص آخر.
تحتفظ حقول النموذج بأسماء API بصيغة camelCase (expectedUpdatedAt: وdoubleOptIn)، وتُمرَّر كوسائط مسمّاة أو كـ Hash واحد، بينما المرشِّحات والخيارات وسائط مسمّاة بصيغة snake_case (status: في list_submissions وoffset_minutes: في analytics). ويعود النموذج في صورة Hash بمفاتيح من نوع Symbol، فيقرأ form[:subscribeUrl] العنوان الذي يستقبل الاشتراكات.
القراءة تتطلب forms:read والتغيير يتطلب forms:write. ويتطلب approve_submission أيضًا contacts:write، لأنه يضيف جهة اتصال. ويتطلب resend_confirmation أيضًا emails:send، وكذلك الاستدعاء الذي يجعل النموذج يرسل بريدًا: تفعيل doubleOptIn، أو تعيين senderAddress أو رسالة التأكيد، أو نشر نموذج ذي تأكيد مزدوج أو استئنافه. ويطلب delete رمز تحقق من رمز وصول OAuth، ولا يطلبه من مفتاح API أبدًا. وإلى أن يحصل الرمز على تحقق، يرفع delete الخطأ OpenEmail::PermissionError مع step_up_required? بقيمة true.
يسجّل subscribe اشتراك الشخص كما تفعل صفحة النموذج، ولا يرسل أي بيانات اعتماد، حتى من عميل يحملها، فيُتجاهل api_key:. وتُمرَّر الإجابات كوسائط مسمّاة أو كـ Hash واحد، بمفاتيح هي مفاتيح حقول النموذج. وكل الاشتراكات من شبكة واحدة تتقاسم حدًّا واحدًا قدره 40 اشتراكًا كل عشر دقائق، لذا فالخادم الذي ينقل اشتراكات أشخاص كثيرين يبلغه سريعًا: أضف من تعرفهم بالفعل عبر audiences.import_contacts بدلًا من ذلك. وبعد تجاوز الحد يرفع الاستدعاء OpenEmail::RateLimitError. ومرّر الصفحة التي كان عليها النموذج بوصفها oe_source:، ولا ترسل oe_started، وأرسل oe_website فارغًا أو لا ترسله أصلًا.
الخطأ 422 من subscribe هو invalid_form_submission، يُرفع في صورة OpenEmail::ValidationError، ويسرد fields الخاص بالخطأ كل إجابة ناقصة أو غير صالحة في صورة Hash فيه key وerror، بأسباب مثل required وemail وoption. ويسمّي OpenEmail::FORM_FIELD_ERRORS كل الأسباب. والـ gem يعمل على خادم. أما المتصفح فيرسل الإجابات بنفسه إلى subscribeUrl الخاص بالنموذج، كمتن JSON أو مع ترويسة Accept: application/json، ويتلقى JSON من أي أصل. ودون أيٍّ منهما يتلقى إعادة توجيه 303 إلى الصفحة المستضافة.
الاستجابة: نموذج
يعيد list صفحة OpenEmail::Page واحدة من النماذج، من الأحدث، دون document وsettings، ويمر list_all وiterate على كل الصفحات. ويعيد get وcreate وupdate وpublish وpause وresume وduplicate النموذج كاملًا في صورة Hash، يضيف document وpublishedDocument وsettings وaudiences وsenderIssue وsenderProblem.
idString- المعرّف الدائم، `frm_` يليه 24 حرفًا ست عشريًا.
statusString- `draft` حتى أول نشر، ثم `live` ما دام يستقبل الاشتراكات و`paused` ما دام لا يستقبلها. ولا يعود النموذج أبدًا إلى `draft`. ويسمّي `OpenEmail::FORM_STATUSES` الحالات الثلاث.
urlString- الصفحة المستضافة للنموذج المنشور، لمشاركتها رابطًا.
subscribeUrlString- المكان الذي يرسل إليه نموذج HTML عادي، أو سكربت في المتصفح، الإجابات.
documentHash- المسودة: `fields` بالترتيب، ونصوص `copy` المحيطة بها، و`style`.
publishedDocumentHash or nil- ما يراه الزوار الآن، أو nil حتى أول نشر.
settingsHash- إلى أين تذهب الاشتراكات وما يحدث بعد كل اشتراك: `audienceIds` و`doubleOptIn` و`senderAddress` ورسالة التأكيد و`successAction` و`redirectUrl` و`notifyAddresses`.
hasUnpublishedChangesBoolean- قيمته true حين تختلف المسودة عما يراه الزوار. وقيمته false دائمًا قبل أول نشر.
senderIssueString or nil- لماذا يتعذّر على نموذج ذي تأكيد مزدوج إرسال رسائل التأكيد الآن: `missing` أو `not_sendable` أو `not_allowed`. ويكون nil حين يمكنه ذلك. ويسمّي `OpenEmail::FORM_SENDER_ISSUES` الثلاثة.
statsHash- `views` و`submissions` و`added` و`pending` و`lastSubmittedAt`، محسوبةً لحظة القراءة.
الردود
يرقّم list_submissions الصفحات من الأحدث، مع q: للبحث في عناوين البريد الإلكتروني وstatus: لاختيار pending أو added، ويمر list_all_submissions وiterate_submissions على كل الصفحات. ويسمّي OpenEmail::FORM_SUBMISSION_STATUSES الحالتين. وكل رد على النموذج Hash يحتفظ بالإجابات كما أُرسلت، بتسمياتها، فتبقى قراءته صحيحة بعد تغيّر النموذج.
يعيد resend_confirmation الرد مع confirmationSent. وتكون قيمته false حين لا يخرج شيء: فالعنوان الواحد يتلقى تأكيدًا واحدًا لكل نموذج كل عشر دقائق وخمسة في اليوم على مستوى مساحة العمل، والرد المضاف لا يتلقى أي تأكيد. ويعلّم expired اشتراكًا معلّقًا انتهت صلاحية أحدث رابط له.