ضبط تجربة العارض والقارئ

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

تضبط نقاط النهاية الخمس هذه كيفية تقديم كتيّب واحد لنفسه في العارض. تستهدف كلٌّ منها كتيّبًا واحدًا عبر {flipbookId} الخاص به وتحدّث جانبًا واحدًا من تجربة العرض والقراءة:

• أظهِر أو أخفِ أزرار شريط أدوات العارض كلًّا على حِدة (التنزيل، والطباعة، والمشاركة، وملء الشاشة، والتكبير، والصور المصغّرة، وغيرها).
• اضبط تنقّل القارئ — الصور المصغّرة للصفحات، وجدول المحتويات، وكيفية انتقال القرّاء بين الصفحات.
• فعّل أو عطّل التقليب التلقائي للصفحات وحدّد فترته.
• حدّد أو امسح مقطع موسيقى الخلفية الذي يُشغَّل في العارض.
• حدّد المحتوى المعروض في الزوايا الأربع (الترويسة/التذييل) لإطار العارض.

قبل أن تبدأ

• مفتاح 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.

اضبط أدوات العارض

يُظهِر أو يُخفي أزرار شريط أدوات العارض كلًّا على حِدة (التنزيل، والطباعة، والمشاركة، وملء الشاشة، والتكبير، والصور المصغّرة، وغيرها).

curl -X PUT 'https://go.fliplink.me/api/set-viewer-controls/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'IsShowControls=true' \
  --data-urlencode 'IsPrint=false' \
  --data-urlencode 'IsDownload=false' \
  --data-urlencode 'IsThumbnails=true' \
  --data-urlencode 'IsSearch=true' \
  --data-urlencode 'IsSound=true' \
  --data-urlencode 'IsFullscreen=true' \
  --data-urlencode 'IsZoom=true' \
  --data-urlencode 'IsNotes=false'

الاستجابة:

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

اضبط تنقّل القارئ

يضبط تنقّل القارئ في العارض — كيفية انتقال القرّاء بين الصفحات. حقول الجسم الأربعة:

• BookLayout (رقم) — تخطيط صفحة رقمي. ويُخزِّن الـ API أي قيمة ترسلها.
• ScrollBehaviour (رقم) — وضع تمرير رقمي؛ والافتراضي 1. ويُفسَّر معنى كل قيمة على جانب العارض، ويُخزِّن الـ API أي قيمة ترسلها.
• IsNavFirstLast (boolean، true/false) — يبدّل التنقّل إلى الصفحة الأولى/الأخيرة.
• IsRightToLeft (boolean، true/false) — يضبط القراءة من اليمين إلى اليسار.

ملاحظة: تنطبق إعدادات تنقّل القارئ هذه على الكتيّبات فقط. أما على عنصر المستند فتُتجاهَل — ويردّ الـ API This setting applies to Flipbook items only.

curl -X PUT 'https://go.fliplink.me/api/set-reader-navigation/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'IsNavFirstLast=true' \
  --data-urlencode 'BookLayout=1' \
  --data-urlencode 'IsRightToLeft=false' \
  --data-urlencode 'ScrollBehaviour=1'

الاستجابة:

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

اضبط التقليب التلقائي

يفعّل أو يعطّل التقليب التلقائي للصفحات في العارض وفترته. وقيمة AutoFlipInSecs بـالميلي ثانية رغم اسمها: 0 = مُطفأ، و3000 = 3 ثوانٍ، و5000 = 5 ثوانٍ، وهكذا.

curl -X PUT 'https://go.fliplink.me/api/set-auto-flip/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'AutoFlipInSecs=0'

الاستجابة:

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

اضبط موسيقى الخلفية

يحدّد أو يمسح مقطع موسيقى الخلفية الذي يُشغَّل في العارض. استخدم اسم ملف مقطع محدّد مسبقًا من /api/list-background-music في BackgroundMusic، أو رابط موسيقى مرفوعة مخصّصة في BackgroundMusicCustom.

curl -X PUT 'https://go.fliplink.me/api/set-background-music/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'BackgroundMusic=' \
  --data-urlencode 'BackgroundMusicCustom=' \
  --data-urlencode 'IsBackgroundMusicLoop=false'

الاستجابة:

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

اضبط تخطيط الترويسة/التذييل

يحدّد المحتوى المعروض في الزوايا الأربع (الترويسة/التذييل) لإطار العارض: TopLeft وTopRight وBottomLeft وBottomRight.

curl -X PUT 'https://go.fliplink.me/api/set-header-footer-layout/96216' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'TopLeft=' \
  --data-urlencode 'TopRight=' \
  --data-urlencode 'BottomLeft=' \
  --data-urlencode 'BottomRight='

الاستجابة:

{
  "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: …".

قيمة Result بـ "OK" تعني أن التغيير طُبِّق؛ وإلا فاقرأ Message لمعرفة السبب.