בשלב מסוים צוות מפסיק ליצור קישורים ביד. המוצר צריך קישור שיתוף לכל משתמש, מערכת ניהול התוכן צריכה ליצור URL מקוצר כשפוסט מתפרסם, וכלי הקמפיינים רוצה קישור במעקב לכל קריאייטיב. אינטגרציה למפתחים ליצירת קישורים ממותגים במעקב הופכת את המקצר לפונקציה שהמערכות שלכם קוראות לה.
המדריך הזה עובר על האינטגרציה מקצה לקצה: מה להחליט לפני שכותבים קוד, איך עובדים האימות וקריאת היצירה, איך הופכים קישורים למדידים בלי לשבור את הייחוס, מקרי הקצה של הפניות שגורמים לבעיות, איפה webhooks משתלבים, ואיך בודקים את הכול. ה-API של LinkPilot משמש כדוגמה, והמבנה מתאים לרוב הפלטפורמות.
קודם מחליטים על הארכיטקטורה
ארבע החלטות, שמתקבלות פעם אחת, חוסכות את רוב העבודה החוזרת.
- אילו מערכות יוצרות קישורים, ובאיזה טריגר: אירוע פרסום, פעולה של משתמש, שמירה של רשומת קמפיין.
- אילו שדות בשליטת מי שקורא ל-API. בדרך כלל היעד והתגיות; לפעמים סיומת הקישור. רק לעיתים רחוקות הדומיין, שצריך להיות הגדרה לכל סביבת עבודה או לכל לקוח.
- איך נתוני הקמפיין ממופים למעקב. הקמפיין, הערוץ ומקום הפרסום במערכת שלכם הופכים לתגיות על הקישור ולפרמטרי UTM על היעד. החליטו על המיפוי ושימו אותו בפונקציה אחת.
- קישור ישיר, קישור עומק או דף גיבוי. קישור לתוך אפליקציה בנייד צריך גיבוי באתר למי שאין לו את האפליקציה. החליטו אם המקצר מטפל בזה או היעד שלכם.
כתבו את ההחלטות האלה. האינטגרציה היא בעיקר קוד מקשר, והקוד הזה צריך להיות משעמם.
אימות עם מפתחות מוגבלים
ה-API של LinkPilot מאמת עם מפתחות bearer שמתחילים ב-lp_live_, נוצרים בלוח הבקרה וזמינים בכל תוכנית, כולל Free. כל מפתח שייך לסביבת עבודה, ולכן אינטגרציה של סוכנות משתמשת במפתח אחד לכל סביבת עבודה של לקוח, והקישורים נוחתים במקום הנכון מעצם המבנה.
curl https://uselinkpilot.com/api/v1/me \
-H "Authorization: Bearer lp_live_..."
GET /me מחזיר את סביבת העבודה, התוכנית, המגבלות, השימוש הנוכחי ותקציב הקצב של המפתח. קראו לו כשהשירות עולה והציגו את המגבלות ביומנים שלכם, כדי שתגלו תקרה לפני שקמפיין יגלה אותה.
התייחסו למפתח כאל פרטי התחברות של סביבת ייצור: שמרו אותו במנהל סודות, אף פעם לא במאגר קוד או בחבילת front-end, וכשצריך למסור אותו למי שבונה את האינטגרציה, שלחו אותו בקישור סודי חד-פעמי. המדריך למפתחות 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"]
}'
התגובה כוללת את מזהה הקישור, את ה-URL המקוצר ואת המטא-דאטה ששלחתם. שמרו את המזהה ליד הרשומה שלכם; בעזרתו קוראים, מעדכנים או מוחקים את הקישור בהמשך. GET /links מציג את הקישורים מהחדש לישן עם עימוד לפי סמן ({ data, next_cursor }), ו-GET /links/{id} ו-DELETE /links/{id} פועלים על קישור אחד.
כמה כללים ששומרים על האינטגרציה אמינה:
- בנו את כתובת היעד בקוד, כולל תגי UTM, משדות הקמפיין. תגים שמקלידים ביד סוטים עם הזמן. המדריך ל-UTM קובע את המוסכמות.
- תנו לפלטפורמה ליצור את סיומות הקישורים, אלא אם אדם יקרא אותן. כשאתם קובעים סיומות בעצמכם, גזרו אותן מהקמפיין, מהערוץ וממקום הפרסום, באותיות קטנות עם מקפים, ואם יש התנגשות, הוסיפו סיומת קצרה ונסו שוב פעם אחת.
- הפכו את היצירה לאידמפוטנטית. קשרו כל יצירה למזהה הרשומה שלכם, כדי שניסיון חוזר אחרי timeout ימצא את הקישור הקיים במקום ליצור קישור שני. אם הפלטפורמה לא מציעה מפתח אידמפוטנטיות, בדקו ב-
GET /linksאת התגית או את הסיומת שלכם לפני היצירה. - יצירה בכמות היא לולאה עם השהיה. כבדו את תקציב הקצב מ-
/me, האטו כשמתקבל 429, ורשמו ביומן כל כישלון יחד עם הרשומה שהוא שייך אליה.
לסקריפטים ולכלים מקומיים, ה-CLI linkpilot ב-npm עוטף את אותן קריאות, והשרת @uselinkpilot/mcp חושף אותן לסוכני AI. שניהם בקוד פתוח ב-GitHub תחת TetraCoreHQ.
קישורים במעקב בלי לשבור את הייחוס
כל קליק על קישור שנוצר דרך ה-API נרשם בדיוק כמו קליק על קישור שנוצר בלוח הבקרה: שעה, מקור הפניה, מכשיר, דפדפן, מדינה, אזור, סימון בוט ו-hash עם salt במקום כתובת ה-IP. כך מקבלים ספירה ברמת הקישור. הייחוס ביעד עדיין תלוי בכך שה-URL מגיע שלם.
- שמרו על פרמטרי השאילתה לאורך ההפניה. בדקו קישור עם בודק ההפניות, וודאו שתגי ה-UTM נמצאים ב-URL הסופי.
- הימנעו משרשראות. קישור מקוצר שמפנה להפניה נוספת מאבד פרמטרים ומהירות. כוונו לעמוד הסופי.
- החליטו מה אתם אוספים. מדינה ומכשיר הם סטטיסטיקות מצטברות. קישור לכל משתמש שמחובר לרשומת לקוח הוא מידע אישי. המדריך המודרני למעקב אחר קישורים מפרט מה נרשם ומה בכוונה לא.
- תאמו ציפיות בתוך המוצר. ספירת קליקים היא לא ספירת המרות. הציגו את שתיהן, עם תוויות.
טיפול במקרי הקצה של הפניות
- אימות היעד. דחו יעדים שאינם HTTPS, את דומיין המקצר שלכם וכל מה שנמצא ברשימה שחורה, לפני שיוצרים את הקישור. הפניה פתוחה על המותג שלכם היא כלי פישינג.
- קישורים שפג תוקפם, שהושבתו או שלא קיימים. החליטו על דף הגיבוי כשיוצרים את הקישור והגדירו אותו, כך שקישור של קמפיין שהסתיים יגיע לדף הבית ולא לשגיאה. בקישורים מודפסים, עדיף לערוך את היעד מאשר לתת לתוקף לפוג אי פעם.
- קישורי עומק. השתמשו ביעד שמזהה את האפליקציה ועובר לאתר אם היא לא מותקנת, או בתכונה של הפלטפורמה לזה. בדקו בשתי מערכות ההפעלה, עם האפליקציה ובלעדיה.
- קידוד. החילו קידוד URL על היעד לפני שמכניסים אותו ל-JSON, במיוחד כשיש לו מחרוזת שאילתה משלו. קידוד כפול הוא הבאג הנפוץ.
- לוקליזציה. אם קישור מקוצר אחד משרת כמה שפות, את זיהוי השפה עשו ביעד, ולא בסיומת הקישור.
webhooks לאירועים שחשובים
webhooks מאפשרים לשאר המערכות להגיב לפעילות בקישורים בלי תשאול חוזר. LinkPilot חותם כל משלוח בכותרת חתימת HMAC, ושולח אירועים על מחזור החיים של קישור (link.created, link.updated, link.deleted) ושל סוד (secret.created, secret.viewed, secret.burned). אמתו את החתימה לפני הפענוח, אשרו את הקבלה מהר, עבדו מתוך תור ושמרו את מזהי האירועים, כך שניסיונות חוזרים לא יזיקו. נתוני הקליקים הם זרם דיווח ולא webhook; קראו אותם דרך הסטטיסטיקות והייצוא. המדריך לאינטגרציות webhook מסביר איך בונים את הצד המקבל.
בדיקה מקצה לקצה, ואחר כך מעקב שוטף
לפני שהאינטגרציה נוגעת בקמפיין אמיתי:
- צרו קישור עם תגיות הבדיקה שלכם, בסביבת עבודה של staging.
- ודאו שהתגובה כוללת את המזהה ואת ה-URL המקוצר שציפיתם להם.
- לחצו עליו מטלפון וממחשב נייד. ודאו את ההפניה, את תגי ה-UTM בהגעה ואת שני הקליקים בסטטיסטיקות עם סוגי המכשירים הנכונים.
- צרו שוב את אותה רשומה, וודאו שאתם מקבלים את אותו קישור ולא כפילות.
- מחקו אותו, וודאו ש-
link.deletedמגיע לנקודת הקצה של ה-webhook, אם אתם משתמשים בה.
בסביבת הייצור עקבו אחרי שלושה דברים: שיעורי שגיאות ב-API לפי קוד סטטוס, זמן ההשהיה של ההפניה לפי בדיקה סינתטית, והתאמה שבועית של מספר הקישורים בין הרשומות שלכם לבין GET /links. החליפו את מפתח ה-API לפי לוח זמנים, ובכל פעם שמישהו עוזב את הצוות שמחזיק בו.
תעדו את האינטגרציה כמו מוצר פנימי: השדות שהיא מקבלת, כלל סיומות הקישורים, ההתנהגות של דף הגיבוי, המגבלות מ-/me, ולמי מתקשרים כשקמפיין מדווח על אפס קליקים. מי שייגע בה אחריכם ישמח, ולעיתים קרובות אלה תהיו אתם.