विज्ञापन खातों तक पहुँच

​

उपयोगकर्ता खाते बनाम Ad खाते

Ads API का उपयोग करने में दो अलग-अलग प्रकार के खाते शामिल होते हैं: विज्ञापन खाते और X उपयोगकर्ता खाते। Ads API दस्तावेज़ों में, “account” शब्द आमतौर पर विज्ञापन खाते के लिए इस्तेमाल होता है।

• विज्ञापन खाते business.x.com पर पंजीकृत होते हैं और API में account_id से पहचाने जाते हैं। विज्ञापन खाते सीधे फंडिंग स्रोतों से जुड़े होते हैं और एक या अधिक X उपयोगकर्ता खातों की सामग्री को ‘promotable users’ के रूप में इस्तेमाल करते हैं। हर विज्ञापन खाता एक या अधिक X उपयोगकर्ता खातों को अनुमति दे सकता है। विज्ञापन खाता, या “current account,” लगभग हर निष्पादित URL में इन-लाइन :account_id पैरामीटर के रूप में दर्शाया जाता है।
• X उपयोगकर्ता खाते (जैसे @AdsAPI) Ads API में user_id से पहचाने जाते हैं। इनमें से एक या अधिक खाते किसी विज्ञापन खाते से संबद्ध हो सकते हैं। API पर अनुरोध करने वाले प्रमाणीकृत X उपयोगकर्ता खाते को ‘current user’ कहा जाता है। जिन विज्ञापन खातों तक current user की पहुँच है, उनकी सूची GET accounts से प्राप्त की जा सकती है। ‘Promotable users’ ऐसे X हैंडल होते हैं जिन्हें कोई विशिष्ट विज्ञापन खाता प्रमोट कर सकता है। इसके बारे में अधिक जानकारी के लिए, Obtaining Ads Account Access देखें।

​

Ad खाते तक पहुँच के तरीके

ऐसे दो तरीके हैं जिनका उपयोग आप किसी विज्ञापनदाता के खाते के लिए Ads API अनुरोध करने हेतु कर सकते हैं:

1. किसी विज्ञापनदाता की ओर से अनुरोध करना (अनुशंसित)
2. अपने उस खाते का उपयोग करके अनुरोध करना, जिसे किसी विज्ञापनदाता के खाते तक पहुँच दी गई हो; उदाहरण के लिए, कई खातों का समर्थन करने वाली कोई Agency।

यह दस्तावेज़ इन विकल्पों के बीच के अंतर का संक्षिप्त अवलोकन है और इसे हमारे अन्य संसाधनों, जैसे multi-user login FAQ, के साथ पढ़ा जाना चाहिए। 

जैसा कि Authorizing a request में बताया गया है, Ads API के लिए सभी अनुरोधों में Authorization headers आवश्यक होते हैं, जिनमें OAuth 1.0a का उपयोग उस access token के साथ किया जाता है, जो 3-leggedOAuth flow के माध्यम से प्राप्त किया गया हो। आपके ऐप को obtain access tokens करने के लिए वेब-आधारित OAuth flow लागू करना होगा। Ads API डेवलपरों को हमारे X विज्ञापनदाताओं से उनके लॉगिन क्रेडेंशियल साझा करने के लिए कभी नहीं कहना चाहिए।

डिफ़ॉल्ट रूप से, प्रत्येक X developer application में एक स्थिर access token होता है, जिसका उपयोग उस खाते के लिए Ads API अनुरोध करने में किया जा सकता है जो उस ऐप का स्वामी है। ये क्रेडेंशियल 3-legged या PIN-based OAuth flow की आवश्यकता के बिना एकल-खाता उपयोग परिदृश्यों के लिए आदर्श हैं। यदि आप किसी अन्य X Ads Account तक पहुँच नहीं कर रहे हैं, तो नीचे दिए गए चरणों के बजाय इन्हीं single-user क्रेडेंशियल का उपयोग करें।

​

पहुँच के स्तर

​

ऐप-स्तरीय अनुमतियाँ

Ads API के लिए आवेदन करते समय किए गए अनुरोध के अनुसार, प्रत्येक उपयोगकर्ता को पहुँच का एक स्तर दिया जाएगा:

• केवल Conversion: उपयोगकर्ता को Mobile और Web Conversion एंडपॉइंट्स पर पढ़ने और लिखने की पहुँच होगी।
• मानक पहुँच: उपयोगकर्ता को Analytics, Campaign Management, Creatives, Custom Audiences, और Conversion एंडपॉइंट्स पर पढ़ने और लिखने की पहुँच होगी।

ध्यान दें: जिन Ads API डेवलपर्स ने जुलाई 2023 से पहले पहुँच का अनुरोध किया था, उनके लिए पहुँच और अनुमतियों के स्तर अलग हो सकते हैं, और वे पाँच OAuth tokens तक सीमित हो सकते हैं। अतिरिक्त एंडपॉइंट्स तक पहुँच प्राप्त करने या मौजूदा ऐप्स के लिए token सीमाएँ हटाने के बारे में जानने हेतु पहुँच बढ़ाने पर हमारी मार्गदर्शिका देखें।

​

विज्ञापन खाते-स्तर की अनुमतियाँ

जिस प्रत्येक उपयोगकर्ता के पास किसी Ads Account का ऐक्सेस है, उसके पास खाते-स्तर की एक विशिष्ट अनुमति होगी: Account administrator, Ad manager, Campaign analyst, Organic analyst, और Creative Manager; खाते-स्तर की अनुमतियों से संबंधित नवीनतम दस्तावेज़ के लिए business.x.com देखें। यह तय करने के लिए कि वे किन API endpoints और Ads सुविधाओं का ऐक्सेस कर सकते हैं, ऐप्स को Authenticated User Access API endpoint के ज़रिए वर्तमान में प्रमाणित उपयोगकर्ता की अनुमतियाँ प्राप्त करनी चाहिए।

नोट: Conversion API के साथ उपयोग किए जाने वाले किसी भी उपयोगकर्ता टोकन ऐसे उपयोगकर्ताओं के होने चाहिए जिनके पास Account administrator या Ad manager की खाते-स्तर की अनुमतियाँ हों।                                                                                                                                              

​

एक्सेस टोकन प्राप्त करने के तरीके

​

1. किसी विज्ञापनदाता का (User) access token प्राप्त करें

किसी विज्ञापनदाता का access token प्राप्त करने के दो तरीके हैं। सबसे सामान्य तरीका है, अपने web UI के भीतर से सीधे 3-legged OAuth flow का उपयोग करना। जिन applications का कोई सार्वजनिक रूप से सुलभ UI विज्ञापनदाताओं के लिए उपलब्ध नहीं है, वे PIN-based OAuth प्रक्रिया लागू कर सकती हैं। उपयोगकर्ता द्वारा 3-legged flow पूरा करने के बाद, आपके application के पास API के माध्यम से उसके Ads account के लिए अनुरोध करने हेतु credentials होंगे।

OAuth flow के माध्यम से user credentials प्राप्त करना वह तरीका है, जिसकी हम अधिकांश Ads API developers को विज्ञापनदाता खाते तक पहुंच पाने के लिए दृढ़ता से अनुशंसा करते हैं। इससे आप किसी उपयोगकर्ता की ओर से API call कर सकते हैं और उसी उपयोगकर्ता के रूप में कार्रवाइयां कर सकते हैं। ये tokens समाप्त नहीं होते, लेकिन उपयोगकर्ता इन्हें किसी भी समय revoke कर सकता है।

​

2. अपना (Developer) एक्सेस टोकन प्राप्त करें

इस विकल्प के लिए विज्ञापनदाता को business.x.com पर X UI के ज़रिए अपने X Ads खाते में आपके @username को ऐक्सेस देना (या @usernames को) होगा। 3-legged OAuth फ़्लो के माध्यम से आपके खाते के लिए प्राप्त किए गए ऐक्सेस टोकन विज्ञापनदाता के X Ads खाते तक पहुँच सकेंगे।

इससे आप विज्ञापनदाता के OAuth टोकनों के बजाय अपने स्वयं के @username के OAuth टोकनों का उपयोग करके API कॉल कर सकते हैं। इस विकल्प में मुख्य अंतर यह है कि आप Promoted-Only पोस्ट्स केवल तभी बना सकते हैं, जब आपके @username को Post delegation/composer की अनुमति दी गई हो।

खाते पर FULL promotable user की ओर से Promoted-Only पोस्ट्स बनाने की पहुँच पाने के लिए, इस फ़्लो में आपको पोस्ट्स बनाने की अनुमति भी दी जानी चाहिए। इससे GET accounts/:account_id/authenticated_user_access endpoint पर TWEET_COMPOSER permission के ज़रिए ऐक्सेस सक्षम हो जाएगा।

​

इन विधियों के बीच अंतर

	विज्ञापनदाता (उपयोगकर्ता) OAuth टोकन	(Developer) OAuth टोकन  (@username अलग खाते में जोड़ा गया)
Ads अकाउंट तक पहुँच	✔	✔
उपयोगकर्ता की ओर से पोस्ट्स बनाना	✔	✔*
Campaigns प्रबंधित करना	✔	✔
Analytics तक पहुँच	✔	✔
उपयोगकर्ता की ओर से Cards बनाना	✔	✔
X Ads UI के ज़रिए पहुँचने की डेवलपर की क्षमता		✔
रेट लिमिट्स	प्रत्येक विज्ञापनदाता के लिए अलग	प्रत्येक विज्ञापनदाता अकाउंट के लिए अलग

नोट: विवरण के लिए ऊपर दिया गया अपना (Developer) access token प्राप्त करें अनुभाग देखें।

​

उदाहरण उपयोग-परिदृश्य

​

OAuth 3-legged वेब फ़्लो के ज़रिए विज्ञापनदाता का access token

मानक फ़्लो वेब-आधारित है और 3-legged authorization OAuth फ़्लो का उपयोग करता है। यहाँ दिखाए गए स्क्रीनशॉट एक सैंपल का हिस्सा हैं, जिसका सोर्स आप https://github.com/xdevplatform/twauth-web पर देख सकते हैं।

आपके ऐप में किसी चरण पर, अपने ऐप को अधिकृत करने के लिए आपको X पर रीडायरेक्ट करना होगा

जब आप request token के साथ X पर रीडायरेक्ट करते हैं, तो उपयोगकर्ता से आपके ऐप को अधिकृत करने के लिए कहा जाएगा

आपके ऐप को अधिकृत करने के बाद, उपयोगकर्ता को उस callback URL पर रीडायरेक्ट किया जाएगा जो आपने request token जनरेट करते समय दिया था। आप इसका उपयोग इस उपयोगकर्ता के लिए स्थायी access token प्राप्त करने और उसे स्थानीय रूप से स्टोर करने के लिए करेंगे!