إضافة أزرار الحث على الإجراء إلى كتيّب

ما الذي يمكنك فعله

يستطيع عارض الكتيّب عرض أزرار الحث على الإجراء (CTA) التي تربط القرّاء بمكان تختاره. وتتيح لك ثلاث نقاط نهاية ضبطها من الـ API:

• اضبط زر الحث الأساسي — نصه، ورابطه، ولونه، وما إذا كان معروضًا.
• اضبط زر الحث الثانوي — زر ثانٍ يستخدم الحقول ذات اللاحقة 2.
• اضبط قواعد المعاينة — تحكّم فيما إذا كان زر الحث مخفيًا بينما يكون القارئ في المعاينة.

قبل أن تبدأ

• مفتاح API — يُرسَل مع كل طلب إمّا في ترويسة X-Api-Key أو ضمن Authorization: Bearer YOUR_API_KEY.
• الـ flipbookId — المُعرّف الرقمي للكتيّب الذي تريد ضبطه (معطى مسار على النقاط الثلاث). يُعيده create-by-file / create-by-url (بوصفه ID) أو تُعيده list.
• تذهب جميع الطلبات إلى الرابط الأساسي https://go.fliplink.me.
• جسم الطلب يكون بصيغة form-urlencoded (لا JSON) على النقاط الثلاث جميعها — أرسِل كل حقل بـ --data-urlencode.

اضبط زر الحث الأساسي

يضبط زر الحث على الإجراء الأساسي في العارض (النص، والرابط، واللون). الحقول هي IsCTAButton وCTAButtonText وCTAButtonURL (إضافةً إلى حقول اللون) — لا Text/URL/Position. وقيمة CTAButtonURL ببادئة mailto: / tel: تُطبَّع تلقائيًا على جانب الخادم.

curl -X PUT 'https://go.fliplink.me/api/set-cta-primary/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'IsCTAButton=false' \
  --data-urlencode 'CTAButtonText=' \
  --data-urlencode 'CTAButtonColor=' \
  --data-urlencode 'CTAButtonURL=' \
  --data-urlencode 'CTAButtonTextColor='

الاستجابة:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

اضبط زر الحث الثانوي

يضبط زر الحث على الإجراء الثانوي في العارض. يستخدم الزر الثانوي الحقول ذات اللاحقة 2 — IsCTAButton2 وCTAButtonText2 وCTAButtonURL2 (إضافةً إلى حقول اللون ذات اللاحقة 2).

curl -X PUT 'https://go.fliplink.me/api/set-cta-secondary/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'IsCTAButton2=false' \
  --data-urlencode 'CTAButtonText2=' \
  --data-urlencode 'CTAButtonColor2=' \
  --data-urlencode 'CTAButtonTextColor2=' \
  --data-urlencode 'CTAButtonURL2='

الاستجابة:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

اضبط قواعد المعاينة

يضبط متى يُعرَض زر الحث على الإجراء للقرّاء — قاعدة بوابة المعاينة. أرسِل IsCTAHiddenInPreview للتحكّم فيما إذا كان زر الحث مخفيًا بينما يكون القارئ في المعاينة.

curl -X PUT 'https://go.fliplink.me/api/set-cta-preview-rules/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'IsCTAHiddenInPreview=false'

الاستجابة:

{
  "Result": "OK",
  "Message": "Updated successfully"
}

الأخطاء المحتملة

• مفتاح API مفقود أو غير صالح ← HTTP 401. تُعيد هذه الحالة صفحة HTML عادية لعدم التصريح — دون أي جسم JSON. تحقّق من وجود ترويسة X-Api-Key (أو Authorization: Bearer) وصحّتها.
• مُعرّف العنصر غير موجود أو غير مملوك لمفتاحك ← HTTP 200 مع Message: "Item not found".
• حقل مجهول أو مكتوب خطأً في الجسم ← HTTP 200 مع Message: "Unknown field(s) '…'. Expected: …". تحقّق مرّتين من التهجئة الدقيقة للحقول (مثل حقول الزر الثانوي ذات اللاحقة 2).

ملاحظات

• تتشارك النقاط الثلاث معطى المسار {flipbookId} نفسه وبنية النجاح نفسها { "Result": "OK", "Message": "Updated successfully" }.
• يُضبَط الزران الأساسي والثانوي كلٌّ على حِدة — فنقطة الزر الثانوي لا تقبل إلا أسماء الحقول ذات اللاحقة 2.