एक समय के बाद टीम हाथ से लिंक बनाना बंद कर देती है। प्रोडक्ट को हर यूज़र के लिए एक शेयर लिंक चाहिए, CMS को पोस्ट पब्लिश होते ही एक छोटा URL बनाना चाहिए, कैंपेन टूल को हर क्रिएटिव के लिए एक ट्रैक किया गया लिंक चाहिए। ट्रैक होने वाले ब्रांडेड लिंक बनाने का डेवलपर इंटीग्रेशन शॉर्टनर को एक ऐसा फ़ंक्शन बना देता है जिसे आपके सिस्टम कॉल करते हैं।
यह गाइड इंटीग्रेशन को शुरू से आखिर तक समझाती है: कोड लिखने से पहले क्या तय करें, ऑथेंटिकेशन और create कॉल कैसे काम करते हैं, एट्रिब्यूशन तोड़े बिना लिंक को ट्रैक करने लायक कैसे बनाएं, रीडायरेक्ट के कौन-से खास मामले परेशान करते हैं, वेबहुक कहां फ़िट होते हैं, और इसे टेस्ट कैसे करें। उदाहरण के तौर पर LinkPilot का API लिया गया है, पर यही ढांचा ज़्यादातर प्लेटफ़ॉर्म पर लागू होता है।
पहले आर्किटेक्चर तय करें
ये चार फ़ैसले एक बार ले लिए जाएं, तो ज़्यादातर काम दोबारा नहीं करना पड़ता।
- कौन-से सिस्टम लिंक बनाते हैं, और किस ट्रिगर पर: पब्लिश इवेंट, यूज़र का कोई काम, कैंपेन रिकॉर्ड का सेव होना।
- कॉल करने वाले किन फ़ील्ड को तय करते हैं। आम तौर पर डेस्टिनेशन और टैग, कभी-कभी स्लग। डोमेन शायद ही कभी, वह हर वर्कस्पेस या हर क्लाइंट की सेटिंग होनी चाहिए।
- कैंपेन डेटा ट्रैकिंग से कैसे जुड़ता है। आपके सिस्टम का कैंपेन, चैनल और प्लेसमेंट लिंक पर टैग और डेस्टिनेशन पर UTM पैरामीटर बन जाते हैं। यह मैपिंग तय करें और इसे एक ही फ़ंक्शन में रखें।
- डायरेक्ट लिंक, डीप लिंक या फ़ॉलबैक। मोबाइल ऐप के अंदर ले जाने वाले लिंक को उन लोगों के लिए वेब फ़ॉलबैक चाहिए जिनके पास ऐप नहीं है। तय करें कि यह शॉर्टनर संभालेगा या आपका डेस्टिनेशन।
इन्हें लिख लें। इंटीग्रेशन ज़्यादातर जोड़ने वाला कोड है, और यह कोड उबाऊ होना चाहिए।
सीमित दायरे वाली API keys से ऑथेंटिकेट करें
LinkPilot का API ऐसी bearer API keys से ऑथेंटिकेट करता है जो lp_live_ से शुरू होती हैं। ये डैशबोर्ड में बनती हैं और Free समेत हर प्लान पर मिलती हैं। हर API key एक वर्कस्पेस की होती है, इसलिए एजेंसी का इंटीग्रेशन हर क्लाइंट वर्कस्पेस के लिए एक API key इस्तेमाल करता है, और लिंक अपने आप सही जगह पहुंचते हैं।
curl https://uselinkpilot.com/api/v1/me \
-H "Authorization: Bearer lp_live_..."
GET /me वर्कस्पेस, प्लान, सीमाएं, मौजूदा इस्तेमाल और API key का रेट बजट लौटाता है। इसे स्टार्टअप पर कॉल करें और सीमाओं को अपने लॉग में दिखाएं, ताकि किसी सीमा का पता कैंपेन से पहले आपको चले।
API key को प्रोडक्शन सिस्टम की लॉगिन की जानकारी की तरह संभालें: इसे सीक्रेट मैनेजर में रखें, कभी किसी रिपॉज़िटरी या फ़्रंट-एंड बंडल में नहीं, और जब इसे इंटीग्रेशन बनाने वाले किसी व्यक्ति को सौंपना हो, तो वन-टाइम सीक्रेट लिंक से भेजें। API key गाइड में सौंपने और रोटेट करने का तरीका है।
लिंक बनाएं
create कॉल डेस्टिनेशन और कुछ वैकल्पिक फ़ील्ड लेती है।
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"]
}'
जवाब में लिंक का ID, छोटा URL और आपका भेजा हुआ मेटाडेटा होता है। ID को अपने रिकॉर्ड के साथ स्टोर करें। बाद में लिंक को पढ़ने, अपडेट करने या डिलीट करने के लिए यही काम आता है। GET /links लिंक की सूची सबसे नए से शुरू करके, कर्सर पेजिनेशन ({ data, next_cursor }) के साथ देता है, और GET /links/{id} और DELETE /links/{id} किसी एक लिंक पर काम करते हैं।
कुछ नियम जो इंटीग्रेशन को भरोसेमंद रखते हैं:
- डेस्टिनेशन URL कोड में बनाएं, UTM टैग समेत, अपने कैंपेन फ़ील्ड से। हाथ से टाइप किए टैग धीरे-धीरे बिगड़ जाते हैं। UTM प्लेबुक में नियम तय हैं।
- स्लग प्लेटफ़ॉर्म को बनाने दें, जब तक कोई इंसान उन्हें पढ़ने वाला न हो। जब आप खुद स्लग तय करें, तो उन्हें कैंपेन, चैनल और प्लेसमेंट से बनाएं, छोटे अक्षरों और हाइफ़न में, और टकराव होने पर एक छोटा सफ़िक्स जोड़कर एक बार फिर कोशिश करें।
- लिंक बनाने को idempotent बनाएं। हर create को अपने रिकॉर्ड ID से जोड़ें, ताकि टाइमआउट के बाद दोबारा कोशिश करने पर दूसरा लिंक न बने, बल्कि पहले से बना लिंक मिल जाए। अगर प्लेटफ़ॉर्म idempotency key नहीं देता, तो बनाने से पहले
GET /linksमें अपना टैग या स्लग जांच लें। - बल्क का मतलब है बैकऑफ़ के साथ लूप।
/meसे मिले रेट बजट का पालन करें, 429 आने पर रुककर दोबारा कोशिश करें, और हर विफलता को उस रिकॉर्ड के साथ लॉग करें जिससे वह जुड़ी थी।
स्क्रिप्ट और लोकल टूल के लिए npm पर मौजूद linkpilot CLI यही कॉल देता है, और @uselinkpilot/mcp सर्वर इन्हें AI एजेंट के लिए उपलब्ध कराता है। दोनों GitHub पर TetraCoreHQ के तहत ओपन सोर्स हैं।
एट्रिब्यूशन तोड़े बिना लिंक को ट्रैक करने लायक बनाएं
API से बने लिंक पर हर क्लिक ठीक वैसे ही दर्ज होता है जैसे डैशबोर्ड में बने लिंक पर: समय, रेफ़रर, डिवाइस, ब्राउज़र, देश, क्षेत्र, बॉट फ़्लैग, और IP की जगह एक सॉल्टेड हैश। इससे आपको लिंक के स्तर की गिनती मिलती है। डेस्टिनेशन पर एट्रिब्यूशन अब भी इस पर निर्भर है कि URL सही-सलामत पहुंचे।
- रीडायरेक्ट के दौरान क्वेरी पैरामीटर बचाकर रखें। रीडायरेक्ट चेकर से लिंक टेस्ट करें और पक्का कर लें कि आखिरी URL पर UTM टैग मौजूद हैं।
- रीडायरेक्ट चेन से बचें। जो शॉर्ट लिंक किसी दूसरे रीडायरेक्ट पर भेजता है, उसमें पैरामीटर भी खोते हैं और रफ़्तार भी। सीधे आखिरी पेज की ओर इशारा करें।
- तय करें कि आप क्या इकट्ठा करते हैं। देश और डिवाइस सामूहिक एनालिटिक्स हैं। ग्राहक के रिकॉर्ड से जुड़ा हर यूज़र का अलग लिंक निजी डेटा है। लिंक ट्रैकिंग की आधुनिक गाइड बताती है कि क्या दर्ज होता है और क्या जान-बूझकर नहीं।
- प्रोडक्ट में साफ़ बताएं कि क्या उम्मीद करें। क्लिक की गिनती कन्वर्ज़न की गिनती नहीं है। दोनों दिखाएं, लेबल के साथ।
रीडायरेक्ट के खास मामलों को संभालें
- डेस्टिनेशन की जांच। लिंक बनाने से पहले बिना HTTPS वाले डेस्टिनेशन, आपके अपने शॉर्टनर डोमेन, और ब्लॉकलिस्ट में मौजूद हर चीज़ को खारिज करें। आपके ब्रांड पर खुला रीडायरेक्ट फ़िशिंग का औज़ार है।
- एक्सपायर हुए, बंद किए गए या गायब लिंक। लिंक बनाते समय ही फ़ॉलबैक पेज तय करके सेट कर दें, ताकि बंद हो चुका कैंपेन लिंक किसी एरर पर नहीं, होमपेज पर पहुंचे। छपे हुए लिंक के लिए, उन्हें कभी एक्सपायर होने देने के बजाय डेस्टिनेशन बदलना बेहतर है।
- डीप लिंक। ऐसा डेस्टिनेशन इस्तेमाल करें जो ऐप को पहचाने और न मिलने पर वेब पर ले जाए, या इसके लिए प्लेटफ़ॉर्म का कोई फ़ीचर। दोनों ऑपरेटिंग सिस्टम पर, ऐप इंस्टॉल होने और न होने, दोनों हालात में टेस्ट करें।
- एन्कोडिंग। डेस्टिनेशन को JSON में डालने से पहले URL-एन्कोड करें, खासकर जब उसकी अपनी क्वेरी स्ट्रिंग हो। दोहरी एन्कोडिंग सबसे आम बग है।
- भाषाएं। अगर एक शॉर्ट लिंक कई भाषाओं के लिए है, तो भाषा की पहचान डेस्टिनेशन पर करें, स्लग में नहीं।
ज़रूरी इवेंट के लिए वेबहुक जोड़ें
वेबहुक से आपका बाकी स्टैक बार-बार पूछे बिना लिंक की गतिविधि पर प्रतिक्रिया दे सकता है। LinkPilot हर डिलीवरी को HMAC सिग्नेचर हेडर से साइन करता है, और लिंक के जीवनचक्र (link.created, link.updated, link.deleted) और सीक्रेट के जीवनचक्र (secret.created, secret.viewed, secret.burned) पर वेबहुक भेजता है। पार्स करने से पहले सिग्नेचर जांचें, डिलीवरी मिलने की पुष्टि तुरंत करें, प्रोसेसिंग एक क्यू से करें, और इवेंट ID स्टोर करें ताकि दोबारा आई डिलीवरी से कोई नुकसान न हो। क्लिक डेटा वेबहुक नहीं, रिपोर्टिंग स्ट्रीम है। इसे एनालिटिक्स और एक्सपोर्ट से पढ़ें। वेबहुक इंटीग्रेशन गाइड में रिसीवर बनाने का तरीका है।
शुरू से आखिर तक टेस्ट करें, फिर नज़र रखें
इंटीग्रेशन किसी असली कैंपेन तक पहुंचे, उससे पहले:
- स्टेजिंग वर्कस्पेस में अपने टेस्ट टैग के साथ एक लिंक बनाएं।
- पक्का कर लें कि जवाब में वही ID और छोटा URL है जिसकी आपको उम्मीद है।
- फ़ोन और लैपटॉप से उस पर क्लिक करें। रीडायरेक्ट, पहुंचने पर UTM टैग, और एनालिटिक्स में सही डिवाइस प्रकार के साथ दोनों क्लिक की पुष्टि करें।
- वही रिकॉर्ड फिर से बनाएं और पक्का कर लें कि आपको वही लिंक मिलता है, डुप्लिकेट नहीं।
- उसे डिलीट करें, और अगर आप वेबहुक इस्तेमाल करते हैं, तो पक्का कर लें कि
link.deletedआपके एंडपॉइंट पर पहुंचता है।
प्रोडक्शन में तीन चीज़ों पर नज़र रखें: स्टेटस कोड के हिसाब से API एरर रेट, सिंथेटिक जांच से रीडायरेक्ट में लगने वाला समय, और हर हफ़्ते आपके रिकॉर्ड और GET /links के बीच लिंक की गिनती का मिलान। API key को तय समय पर रोटेट करें, और जिस टीम के पास वह है, उससे कोई भी व्यक्ति जाए तो हर बार रोटेट करें।
इंटीग्रेशन का डॉक्यूमेंटेशन किसी अंदरूनी प्रोडक्ट की तरह लिखें: यह कौन-से फ़ील्ड लेता है, स्लग का नियम, फ़ॉलबैक कैसे काम करता है, /me से मिली सीमाएं, और जब कोई कैंपेन शून्य क्लिक दिखाए तो किसे कॉल करना है। इस पर अगला काम करने वाला व्यक्ति इसके लिए आभारी होगा, और अक्सर वह आप ही होते हैं।