في مرحلة ما يتوقف الفريق عن إنشاء الروابط يدويًا. فالمنتج يحتاج إلى رابط مشاركة لكل مستخدم، ونظام إدارة المحتوى يجب أن ينشئ عنوان URL مختصرًا عند نشر كل مقال، وأداة الحملات تريد رابطًا متتبَّعًا لكل تصميم إعلاني. والتكامل البرمجي لإنشاء روابط قابلة للتتبع بنطاقك الخاص يحوّل أداة الاختصار إلى دالة تستدعيها أنظمتك.
يشرح هذا الدليل التكامل من أوله إلى آخره: ما تقرره قبل كتابة الكود، وكيف تعمل المصادقة واستدعاء الإنشاء، وكيف تجعل الروابط قابلة للتتبع دون أن تفسد الإسناد، وحالات إعادة التوجيه الخاصة التي تسبب المتاعب، ومكان webhooks في التكامل، وكيف تختبر كل ذلك. نتخذ واجهة API في LinkPilot مثالًا عمليًا، والبنية نفسها تنطبق على معظم المنصات.
حدّد البنية أولًا
أربعة قرارات تتخذها مرة واحدة فتوفر عليك معظم إعادة العمل.
- أي الأنظمة تنشئ الروابط، وما الحدث الذي يطلق الإنشاء: نشر مقال، أو إجراء من المستخدم، أو حفظ سجل حملة.
- أي الحقول يتحكم فيها المستدعي. عادةً الوجهة والوسوم، وأحيانًا نهاية الرابط. ونادرًا النطاق، فالأفضل أن يكون إعدادًا لكل مساحة عمل أو لكل عميل.
- كيف تتحول بيانات الحملة إلى تتبع. تصبح الحملة والقناة وموضع النشر في نظامك وسومًا على الرابط ومعلمات UTM على الوجهة. حدّد هذا التحويل وضعه في دالة واحدة.
- رابط مباشر أم رابط عميق أم صفحة بديلة. الرابط الذي يفتح تطبيقًا على الهاتف يحتاج إلى بديل على الويب لمن لا يملك التطبيق. قرّر هل تتولى أداة الاختصار ذلك أم وجهتك.
دوّن هذه القرارات. فالتكامل في معظمه كود ربط، وكود الربط يجب أن يكون مملًا.
المصادقة بمفاتيح محددة النطاق
تستخدم واجهة API في LinkPilot للمصادقة مفاتيح Bearer تبدأ بالبادئة
lp_live_، تنشئها من لوحة التحكم، وهي متاحة في كل الخطط ومنها Free. وينتمي
كل مفتاح إلى مساحة عمل واحدة، فيستخدم تكامل الوكالة مفتاحًا لكل مساحة عمل
عميل، وتصل الروابط إلى المكان الصحيح بحكم التصميم.
curl https://uselinkpilot.com/api/v1/me \
-H "Authorization: Bearer lp_live_..."
يعيد GET /me مساحة العمل والخطة والحدود والاستخدام الحالي وحصة الطلبات
المتاحة للمفتاح. استدعه عند بدء التشغيل واعرض الحدود في سجلاتك، لتعرف بوجود
سقف قبل أن تصطدم به حملة.
تعامل مع المفتاح كبيانات دخول لبيئة الإنتاج: خزّنه في مدير أسرار، ولا تضعه أبدًا في مستودع كود أو في حزمة الواجهة الأمامية، وعندما تضطر إلى تسليمه لمن يبني التكامل، أرسله عبر رابط سري لمرة واحدة. ويشرح دليل مفاتيح API التسليم والتدوير.
أنشئ الرابط
يأخذ استدعاء الإنشاء الوجهة وبضعة حقول اختيارية.
curl -X POST https://uselinkpilot.com/api/v1/links \
-H "Authorization: Bearer lp_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/launch?utm_source=newsletter&utm_medium=email&utm_campaign=oct-launch",
"slug": "oct-launch-email",
"domain": "go.example.com",
"title": "October launch, newsletter",
"tags": ["oct-launch", "email"]
}'
تحمل الاستجابة معرّف الرابط والعنوان المختصر والبيانات الوصفية التي أرسلتها.
خزّن المعرّف بجانب سجلك، فهو ما تستخدمه لاحقًا لقراءة الرابط أو تحديثه أو
حذفه. ويعرض GET /links الروابط من الأحدث إلى الأقدم مع ترقيم صفحات بالمؤشر
({ data, next_cursor })، ويعمل GET /links/{id} و DELETE /links/{id} على
رابط واحد.
قواعد قليلة تُبقي التكامل سليمًا:
- ابنِ عنوان URL للوجهة في الكود، ومعه وسوم UTM، من حقول حملتك. فالوسوم المكتوبة يدويًا تنحرف مع الوقت. ويحدد دليل UTM القواعد المتبعة.
- دع المنصة تولّد نهايات الروابط إلا إذا كان شخص سيقرؤها. وإن حددتها بنفسك، فاشتقها من الحملة والقناة وموضع النشر، بأحرف صغيرة مع شرطات، وتعامل مع التعارض بإضافة لاحقة قصيرة وإعادة المحاولة مرة واحدة.
- اجعل الإنشاء آمنًا عند تكراره. اربط كل عملية إنشاء بمعرّف سجلك أنت،
حتى تجد إعادة المحاولة بعد انتهاء المهلة الرابط الموجود بدلًا من إنشاء رابط
ثانٍ. وإن لم توفر المنصة مفتاحًا لمنع التكرار (idempotency key)، فابحث في
GET /linksعن الوسم أو نهاية الرابط قبل الإنشاء. - الإنشاء بالجملة حلقة مع تراجع تدريجي. التزم بحصة الطلبات التي يعيدها
/me، وتراجع عند الخطأ 429، وسجّل كل إخفاق مع السجل الذي يخصه.
وللسكربتات والأدوات المحلية، تغلّف أداة linkpilot CLI المنشورة على npm
الاستدعاءات نفسها، ويتيحها خادم @uselinkpilot/mcp لوكلاء الذكاء
الاصطناعي. والاثنان مفتوحا المصدر على GitHub تحت حساب TetraCoreHQ.
اجعل الروابط قابلة للتتبع دون إفساد الإسناد
تُسجَّل كل نقرة على رابط أُنشئ عبر API تمامًا كما تُسجَّل على رابط أُنشئ من لوحة التحكم: الوقت، ومصدر الإحالة، والجهاز، والمتصفح، والدولة، والمنطقة، وعلامة الروبوت، وقيمة مجزّأة مع قيمة عشوائية (salted hash) بدل عنوان IP. وهذا يعطيك عدد النقرات على مستوى الرابط. أما الإسناد على الوجهة فما زال يعتمد على وصول عنوان URL سليمًا.
- حافظ على معلمات الاستعلام عبر إعادة التوجيه. اختبر الرابط باستخدام أداة فحص إعادة التوجيه وتأكد من وجود وسوم UTM في عنوان URL النهائي.
- تجنب السلاسل. الرابط المختصر الذي يعيد التوجيه إلى رابط إعادة توجيه آخر يفقد المعلمات والسرعة. وجّهه إلى الصفحة النهائية مباشرة.
- حدّد ما تجمعه. الدولة والجهاز إحصاءات مجمّعة. أما الرابط الخاص بكل مستخدم والمربوط بسجل عميل فهو بيانات شخصية. ويذكر دليل تتبع الروابط الحديث ما يُسجَّل وما لا يُسجَّل عمدًا.
- وضّح التوقعات داخل المنتج. عدد النقرات ليس عدد التحويلات. اعرض الاثنين، ولكل منهما تسميته.
تعامل مع حالات إعادة التوجيه الخاصة
- التحقق من الوجهة. ارفض قبل إنشاء الرابط الوجهات التي لا تستخدم HTTPS، والنطاق الذي تقدّم عليه روابطك المختصرة، وأي عنوان في قائمة حظر. فإعادة التوجيه المفتوحة على علامتك التجارية أداة جاهزة للتصيد.
- الروابط المنتهية أو المعطلة أو المفقودة. حدّد الصفحة البديلة عند إنشاء الرابط واضبطها، حتى يصل رابط الحملة المنتهية إلى الصفحة الرئيسية لا إلى رسالة خطأ. وفي الروابط المطبوعة، فضّل تعديل الوجهة على أن تترك صلاحية الرابط تنتهي أصلًا.
- الروابط العميقة. استخدم وجهة تكتشف وجود التطبيق وتعود إلى الويب إن لم يكن موجودًا، أو ميزة في المنصة تتولى ذلك. واختبر على نظامي التشغيل، مع تثبيت التطبيق ودونه.
- الترميز. رمّز عنوان URL للوجهة قبل وضعه في JSON، خصوصًا إذا كان يحمل سلسلة استعلام خاصة به. والترميز المزدوج هو الخطأ المعتاد.
- تعدد اللغات. إذا كان رابط مختصر واحد يخدم عدة لغات، فاكتشف اللغة على الوجهة لا في نهاية الرابط.
أضف webhooks للأحداث المهمة
تتيح webhooks لبقية أنظمتك أن تستجيب لنشاط الروابط دون استطلاع متكرر.
يوقّع LinkPilot كل إرسال بترويسة توقيع HMAC، ويطلق الأحداث عند تغيّر دورة
حياة الرابط (link.created و link.updated و link.deleted) ودورة حياة
السر (secret.created و secret.viewed و secret.burned). تحقق من التوقيع
قبل تحليل المحتوى، وأرسل الإقرار بسرعة، وعالج الأحداث من طابور، وخزّن
معرّفات الأحداث حتى لا تضر إعادة الإرسال. أما بيانات النقرات فهي تدفق
للتقارير وليست webhook، فاقرأها عبر الإحصاءات والتصدير. ويشرح دليل تكامل
webhooks
بناء جهة الاستقبال.
اختبر من البداية إلى النهاية، ثم واصل المراقبة
قبل أن يقترب التكامل من حملة حقيقية:
- أنشئ رابطًا بوسوم الاختبار في مساحة عمل تجريبية.
- تأكد أن الاستجابة تحمل المعرّف والعنوان المختصر اللذين تتوقعهما.
- انقر عليه من هاتف ومن حاسوب محمول. وتأكد من إعادة التوجيه، ومن وصول وسوم UTM، ومن ظهور النقرتين في الإحصاءات بنوعي الجهازين الصحيحين.
- أنشئ السجل نفسه مرة أخرى وتأكد أنك تحصل على الرابط نفسه، لا على نسخة مكررة.
- احذفه وتأكد من وصول
link.deletedإلى نقطة استقبال webhook لديك إن كنت تستخدمها.
وفي بيئة الإنتاج راقب ثلاثة أمور: معدلات أخطاء API حسب رمز الحالة، وزمن
إعادة التوجيه عبر فحص آلي دوري، ومطابقة أسبوعية لعدد الروابط بين سجلاتك
و GET /links. ودوّر مفتاح API وفق جدول زمني، وكلما غادر أحد أعضاء الفريق
الذي يحمل المفتاح.
وثّق التكامل كأنه منتج داخلي: الحقول التي يقبلها، وقاعدة نهايات الروابط،
وسلوك الصفحة البديلة، والحدود التي يعيدها /me، ومن تتصل به عندما تُظهر حملة
صفر نقرات. وسيشكرك الشخص التالي الذي يعمل عليه، وكثيرًا ما يكون أنت.