PollsLivePollsLive
← All posts

June 28, 2026 · 8 min read

ادمج الاستطلاعات المباشرة في منتجك عبر واجهة PollsLive البرمجية

أنشئ استطلاعات، وأدر جلسات مباشرة، واقرأ النتائج، واستقبل ويب هوكس من شيفرتك الخاصة: دليل للمطورين لدمج استطلاعات تفاعلية داخل SaaS أو تطبيق مجتمعك.

By Tom Becker · Full-stack developer·DevelopersHow-to

إن كان لمنتجك جمهور — أداة ندوات، أو نظام إدارة تعلّم، أو منصة مجتمع، أو تطبيق فعاليات — فعاجلًا أو آجلًا ستريد استطلاعات داخله. بناء التصويت الفوري ومكافحة الاحتيال وواجهة نتائج من الصفر أشهر من العمل. أما دمج PollsLive فأمسية واحدة. هذا هو المسار للمطورين: أنشئ استطلاعًا، وأدرج التضمين، واقرأ النتائج، واستقبل ويب هوكس، باستدعاءات حقيقية لـ /api/v1.

المصادقة: رمز Bearer واحد

أنشئ مفتاح API لمساحة العمل من Studio → Developers (تبدو هكذا `plv_live_…`) وأرسله كرمز Bearer. لا رقصة OAuth للاستخدام خادم-إلى-خادم؛ وOAuth client-credentials متاح حين تحتاج نطاقًا لكل مستأجر.

auth
export POLLSLIVE_API=https://pollslive.com/api/v1
export POLLSLIVE_KEY=plv_live_xxxxxxxxxxxxxxxxxxxx

# Every request carries the key as a Bearer token:
#   Authorization: Bearer $POLLSLIVE_KEY
# Rate limit: 120 requests/min per key (HTTP 429 if exceeded).

الخطوة 1 — أنشئ استطلاعًا من شيفرتك

الاستطلاع عرض مُكتَّب الأنواع: content.questions مصفوفة شرائح، لكل منها مُميِّز kind. POST /polls يعيد الاستطلاع الجديد، بما في ذلك الـ slug الخاص به، وهو كل ما تحتاجه لتضمينه.

POST /polls
curl -sS -X POST "$POLLSLIVE_API/polls" \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Which feature should we build next?",
    "renderingMode": "ASYNC",
    "content": {
      "questions": [{
        "id": "next",
        "kind": "multiple_choice",
        "text": "Which feature should we build next?",
        "options": [
          { "id": "a", "label": "Dark mode" },
          { "id": "b", "label": "Mobile app" },
          { "id": "c", "label": "Public API" }
        ]
      }]
    }
  }'
# → { "poll": { "slug": "which-feature-x7f2", ... } }

الخطوة 2 — أدرجه في واجهتك

ضع الاستطلاع في أي صفحة بإطار iframe من سطر واحد: دون SDK، ودون مكتبة عميل، ودون متعقّبات طرف ثالث ترافقه. يتكيّف مع حاويته ويعمل داخل React أو WordPress أو Webflow أو HTML خام.

embed
<iframe
  src="https://pollslive.com/embed/which-feature-x7f2"
  width="100%" height="520"
  style="border:0;border-radius:12px"
  loading="lazy" title="PollsLive poll"></iframe>

الخطوة 3 — اقرأ النتائج متى احتجتها

احصل على الأعداد عند الطلب للوحاتك الخاصة، أو صدّر CSV للتقارير. تعود النتائج لكل شريحة بالأعداد و(للمقاييس) المتوسطات.

GET results
curl -sS "$POLLSLIVE_API/polls/POLL_ID/results" \
  -H "Authorization: Bearer $POLLSLIVE_KEY"
# → { "questions": [ { "id": "next", "options": [
#       { "id": "a", "label": "Dark mode",  "count": 64 },
#       { "id": "b", "label": "Mobile app", "count": 41 },
#       { "id": "c", "label": "Public API", "count": 95 } ] } ] }

الخطوة 4 — استقبل التحديثات عبر ويب هوكس

استطلاع الواجهة بالاقتراع المتكرر يعمل، لكن الويب هوكس أفضل. سجّل نقطة نهاية فيرسل PollsLive أحداثًا موقّعة بـ HMAC — vote.created وpoll.published وsession.started/ended — كي يتفاعل تطبيقك فوريًا. تحقّق من التوقيع ثم حدّث واجهتك أو أعد توجيه الحدث.

verify a webhook (Node)
import crypto from "node:crypto";

export function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

ذلك هو كامل الدورة: أنشئ، أدرج، اقرأ، تفاعل. وللمرجع الكامل — كل نقطة نهاية ونطاق ونوع حدث — راجع وثائق المطورين، ولمثال عملي، نقل النتائج المباشرة إلى لوحة داخلية عبر الويب هوكس.

ابنِ فوق PollsLive: أنشئ استطلاعات، وأدر جلسات مباشرة، واحصل على النتائج، واستقبل ويب هوكس من شيفرتك الخاصة.

اقرأ وثائق المطورين