🤟🏿 🅿️ ✌️ हम Yandex.Metrica API का उपयोग करके एक विजेट लिख रहे हैं 🤼 🎁 🙍🏽

इतना समय पहले नहीं, Yandex.Metrica ने एक खुले एपीआई की घोषणा की, जिसके साथ आप अपने स्वयं के कार्यक्रम से मेट्रिक के लगभग सभी कार्यों तक पहुँच सकते हैं।
आज मैं इस एपीआई के उपयोग के बारे में थोड़ी बात करना चाहता हूं और इसके आधार पर एंड्रॉइड डिवाइस के लिए एक सरल विजेट कैसे बना सकता हूं।

एपीआई मूल बातें

Yandex.Metrica API REST के सिद्धांत पर बनाया गया है। एपीआई के माध्यम से नियंत्रित किया जा सकता है कि एक संसाधन द्वारा प्रतिनिधित्व किया जाता है: काउंटर, लक्ष्य, फिल्टर, आदि। I.Metrica API सर्वर के HTTP अनुरोधों के माध्यम से संसाधनों (रीडिंग, डिलीट, चेंजिंग) पर संचालन किया जाता है, प्रत्येक प्रकार के ऑपरेशन की अपनी HTTP विधि होती है:

प्राप्त करें: पठन सामग्री
POST: एक संसाधन जोड़ना
PUT: संसाधन परिवर्तन
DELETE: एक संसाधन हटाएं

उदाहरण के लिए, काउंटरों की सूची प्राप्त करने के लिए, आपको काउंटर्स संसाधन: GET /counters को संदर्भित करना होगा। एक काउंटर के बारे में जानकारी प्राप्त करने के लिए, इसके पहचानकर्ता द्वारा संसाधन देखें: GET /counter/{id} । हटाने के लिए, उसी संसाधन का संदर्भ लें, लेकिन DELETE पद्धति का उपयोग कर: DELETE /counter/{id} ।

REST कॉल के लिए इनपुट और परिणाम दो स्वरूपों में एन्कोड किए जा सकते हैं: XML और JSON। भविष्य में, हम JSON का उपयोग प्रोग्रामिंग भाषाओं में प्रयुक्त संरचनाओं पर प्रदर्शित करने के लिए एक अधिक कॉम्पैक्ट और सुविधाजनक प्रारूप के रूप में करेंगे।

स्वाभाविक रूप से, एपीआई के माध्यम से काम करना केवल काउंटरों के साथ संभव है, जो आपके वाई मेट्रिका खाते से एक्सेस किए जाते हैं। खाता स्वामी की पहचान करने के लिए OAuth प्रमाणीकरण का उपयोग किया जाता है। यह बहुत सरलता से व्यवस्थित है। एक डेवलपर जो Yandex.Metrica API का उपयोग करना चाहता है, वह अपने आवेदन को पंजीकृत करता है ( निर्देश देखें) और आवेदन पहचानकर्ता को प्राप्त करता है। आवेदन को पंजीकृत करने के बाद, आप इसके लिए एक डीबगिंग OAuth टोकन प्राप्त कर सकते हैं और तुरंत Metrica API के साथ काम करना शुरू कर सकते हैं। डिबगिंग टोकन एप्लिकेशन को पंजीकृत करने वाले डेवलपर खाते से उपलब्ध काउंटरों के साथ काम करने की अनुमति देगा। प्रत्येक HTTP अनुरोध में टोकन को या तो URL में प्रेषित किया जाना चाहिए, ( ...&oauth_token=<acces_token> ), या HTTP अनुरोध में शीर्ष लेख के रूप में Authorization: OAuth <access_token> ।

एप्लिकेशन के लिए मनमाने ढंग से काउंटरों के साथ काम करने के लिए, और न केवल डेवलपर के लिए उपलब्ध होने के लिए, प्रत्येक एप्लिकेशन उपयोगकर्ता के लिए एक अलग OAuth टोकन आवश्यक है। मैं इसे कैसे प्राप्त कर सकता हूं:

सबसे सुरक्षित तरीका यह है कि जब कोई उपयोगकर्ता किसी विशेष Yandex पृष्ठ पर किसी एप्लिकेशन द्वारा रीडायरेक्ट किया जाता है, तो उसमें लॉग होता है, और (यदि उसने पहले से ऐसा नहीं किया है) तो एप्लिकेशन को उसके काउंटर तक पहुंच देता है। उसके बाद, उपयोगकर्ता को एप्लिकेशन पर वापस भेज दिया जाता है, और जिस URL पर पुनर्निर्देशन जाता है, उसमें इस उपयोगकर्ता के लिए OAuth टोकन वाला पैरामीटर होता है। एप्लिकेशन को इस पैरामीटर को पढ़ना चाहिए और टोकन को याद रखना चाहिए। इस प्रक्रिया का विवरण मैनुअल में वर्णित है।
एप्लिकेशन सीधे उपयोगकर्ता से उपयोगकर्ता नाम और पासवर्ड का अनुरोध करके, यांडेक्स सर्वर के OAuth को पास करके और प्रतिक्रिया में टोकन प्राप्त करके भी टोकन प्राप्त कर सकते हैं। यह विधि कम सुरक्षित है: लॉगिन और पासवर्ड स्पष्ट रूप से अनुरोध और प्रेषित किए जाते हैं।

आरईएसटी के उपयोग के लिए धन्यवाद, एपीआई (रीड अनुरोधों) के साथ सबसे सरल ऑपरेशन सीधे ब्राउज़र से, बिना किसी कोडिंग के संभव है। उदाहरण के लिए, यह अनुरोध I.Metrica API के डेमो खाते में काउंटर के बारे में जानकारी प्रदर्शित करेगा। ऐसा अनुरोध काउंटर की उपस्थिति पर एक रिपोर्ट का उत्पादन करेगा।

REST इंटरफ़ेस की सादगी के बावजूद, उच्च-स्तरीय भाषा में लिखे गए प्रोग्राम में API के पूर्ण उपयोग के लिए, आपको बहुत अधिक इशारों को करने की आवश्यकता है: अनुरोध URL जनरेट करना, HTTP अनुरोध भेजना और परिणाम प्राप्त करना, CSON, त्रुटि हैंडलिंग, आदि को उत्पन्न करना और प्राप्त करना। अपने जीवन को सरल बनाने के लिए, मैंने जावा में मेट्रिक्स एपीआई: मेट्रिका 4 जे के साथ काम करने के लिए एक तैयार पुस्तकालय बनाया। लाइब्रेरी कोड अपाचे लाइसेंस के तहत वितरित किया जाता है, आप इसे अपनी आवश्यकताओं के लिए स्वतंत्र रूप से संशोधित और पूरक कर सकते हैं। आगे मैं आपको बताऊंगा कि इस लाइब्रेरी का उपयोग कैसे करें कि एंड्रॉइड डिवाइस के लिए एक विजेट बनाएं जो साइट ट्रैफ़िक प्रदर्शित करता है।

Metrika4j

Metrika4j आपको Yandex.Metrica के साथ काम करने की अनुमति देता है, परिचित Java अवधारणाओं (कक्षाओं, फ़ंक्शन कॉल, प्रकार) पर काम कर रहा है और HTTP और JSON के साथ निम्न-स्तर के काम के बारे में नहीं सोच रहा है। पुस्तकालय का केंद्रीय इंटरफ़ेस MetrikaApi है । इसमें मीट्रिक की मुख्य संस्थाओं के साथ काम करने के तरीके हैं: काउंटर और रिपोर्ट। अतिरिक्त MetrikaApi (गोल, फिल्टर इत्यादि) के साथ काम मुख्य MetrikaApi वर्ग से प्राप्त अलग-अलग मिनी-एपीआई में किया जाता है।

तरीकों की संरचना मोटे तौर पर REST कॉल की संरचना से मेल खाती है। मैं मीट्रिक एपीआई। REST कॉल में दी गई दलीलें API विधियों में दी गई दलीलों के अनुरूप हैं (रिपोर्टिंग API को छोड़कर, जिस पर हम अलग से चर्चा करेंगे)।
Metrika4j JSON के साथ काम करने के लिए बॉक्स दो पुस्तकालयों का समर्थन करता है: जैक्सन JSON प्रोसेसर और org.json । जैक्सन के लिए, 100% कार्यक्षमता का समर्थन किया गया है, org.json के लिए - रिपोर्ट के साथ काम करने के लिए न्यूनतम पर्याप्त: काउंटरों की सूची को पढ़ना और रिपोर्ट प्राप्त करना। Org.json लाइब्रेरी को एंड्रियोड एपीआई में बनाया गया है, इसलिए इसका उपयोग एंड्रॉइड एप्लिकेशन के लिए सुविधाजनक है। यदि आवश्यक हो, तो डेवलपर JsonMapper और JsonObject इंटरफेस को लागू करके किसी भी अन्य JSON लाइब्रेरी का उपयोग कर सकता है।

Metrika4j का उपयोग करना

पहले आपको MetrikaApi का उपयोग करके MetrikaApi का एक उदाहरण बनाना होगा । बनाते समय, आपको उपयोगकर्ता OAuth टोकन को पास करना होगा:

 //   API,  - API   Jackson JSON processor MetrikaApi api = ApiFactory.createMetrikaAPI( "05dd3dd84ff948fdae2bc4fb91f13e22", new JacksonMapper());

आगे, निर्मित उदाहरण का उपयोग करके, आप कोई भी कार्य कर सकते हैं:

 //       Counter[] myCounters = api.getCounters(); //   Counter newCounter = new Counter(); newCounter.setSite("mysite.ru"); newCounter.setName(" "); Counter createdCounter = api.createCounter(newCounter); //  createdCounter   ,   ,    , //  ,  Id System.out.println(createdCounter.getId()); //   api.deleteCounter(createdCounter.id);

रिपोर्ट के साथ काम करें

मीट्रिक में मौजूद लगभग सभी रिपोर्ट API के माध्यम से उपलब्ध हैं। उपलब्ध रिपोर्ट का सेट रिपोर्ट वर्ग में निहित है। चयनित रिपोर्ट बनाने के लिए, आपको MetrikaApi.makeReportBuilder(Reports report, int counterId) विधि MetrikaApi.makeReportBuilder(Reports report, int counterId) कॉल करना होगा, जो एक विशेष ऑब्जेक्ट - ReportBuilder रिपोर्ट बिल्डर लौटाएगा। रिपोर्ट बिल्डर में, आपको आवश्यक रिपोर्ट पैरामीटर (समय अंतराल, सॉर्टिंग, आदि) निर्धारित करने की आवश्यकता है। जब सभी पैरामीटर सेट हो जाते हैं, तो ReportBuilder.build() विधि को कॉल करें, जो मेट्रिक्स एपीआई को एक HTTP अनुरोध भेजेगा और एक रिपोर्ट लौटाएगा।

 //    " "    id=2138128 ReportBuilder builder = api.makeReportBuilder(Reports.contentPopular, 2138128); //    (  )    Report report = builder.withDateFrom(MetrikaDate.yesterday()) .withDateTo(MetrikaDate.today()) .build();

रिपोर्ट को रिपोर्ट ऑब्जेक्ट के रूप में लौटाया जाता है, जो परिणामों के साथ एक तालिका है, साथ ही कुछ अतिरिक्त जानकारी (योग, तिथि सीमा जिसमें रिपोर्ट संबंधित है, आदि)। परिणाम तालिका की प्रत्येक पंक्ति एक ReportItem ऑब्जेक्ट है, जिसमें से डेटा getXXX(String fieldName) विधियों में से एक का उपयोग करके प्राप्त किया जा सकता है getXXX(String fieldName) का उपयोग करते समय एक getXXX(String fieldName) से मान प्राप्त करने के समान)। Yandex.Metrica API के दस्तावेज़ में प्रत्येक रिपोर्ट के लिए फ़ील्ड नाम और लौटा अतिरिक्त डेटा निर्दिष्ट होना चाहिए।

 //     ReportItem[] items = report.getData(); for (ReportItem item : items) { System.out.printf("pageViews: %4d, url: %s", item.getInt("page_views"), item.getString("url")) .println(); }

Metrika4j के साथ काम करने का अधिक विस्तृत विवरण जावदोक में पाया जा सकता है।

Android के लिए विजेट

Yandex.Metrica और Metrika4j API के रूप में इस तरह के शक्तिशाली उपकरण के निपटान के बाद, आप Yandex.Metrica के लिए वैकल्पिक उपयोगकर्ता इंटरफ़ेस बनाने तक, किसी भी समस्या को हल कर सकते हैं। लेकिन इस लेख के ढांचे के भीतर हम खुद को एक अधिक विनम्र लक्ष्य तक सीमित कर लेंगे: हम एंड्रॉइड के लिए एक विजेट बनाएंगे जो साइट पर वर्तमान ट्रैफ़िक दिखाएगा। विजेट का स्रोत कोड MetrikaWidget प्रोजेक्ट में GitHub पर उपलब्ध है। Metrika4j कोड की तरह, यह न्यूनतम लाइसेंस प्रतिबंधों के साथ स्वतंत्र रूप से वितरित किया जाता है।

OAuth प्राधिकरण

MetrikaApi और प्राधिकरण बनाकर शुरू करते हैं। आवेदन केवल एक खाते के साथ काम करता है, इसलिए आप MetrikaApi उदाहरण MetrikaApi बना सकते हैं। इसका कोड ग्लोबल्स वर्ग में निहित है।

 private static MetrikaApi api; public static synchronized MetrikaApi getApi(Context context) { if (api == null) { //   OAuth token  SharedPreferences String token = getOAuthToken(context); if (token == null) { throw new AuthException(); } else { //   org.json,   Android api = ApiFactory.createMetrikaAPI(token, new OrgJsonMapper()); } } return api; }

यदि आवेदन पहली बार शुरू होता है और OAuth टोकन अभी तक साझा किए गए सम्मेलनों में नहीं है, तो आपको इसे प्राप्त करने की आवश्यकता है। ऐसा करने के लिए, टोकन अनुरोध URL पर जाएं:

 Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse("https://oauth.yandex.ru/authorize?response_type=token&client_id=1359488e196b4bfa92615d0885b106d4")); startActivity(intent);

उपयोगकर्ता के लिए, यह खुले हुए पृष्ठ की तरह दिखाई देगा "आवेदन यैंडेक्स पर आपके डेटा तक पहुंच का अनुरोध कर रहा है।" मान लें कि उपयोगकर्ता ने सफलतापूर्वक लॉग इन किया और पहुंच की अनुमति दी। फिर मज़ा शुरू होता है: वेब इंटरफ़ेस से टोकन को वापस हमारे आवेदन में कैसे स्थानांतरित किया जाए? ऐसा करने के लिए, आपको हमारे अनुप्रयोग के लिए विशिष्ट प्रोटोकॉल के लिए हैंडलर के रूप में एप्लिकेशन में एक गतिविधि को पंजीकृत करने की आवश्यकता है (विशिष्ट ताकि हमारा हैंडलर अन्य अनुप्रयोगों के साथ ओवरलैप न हो)। AndroidManifest.xml निम्नलिखित निर्दिष्ट करें:

 <activity android:name="ru.metrikawidget.AuthTokenActivity" android:label="OAuth"> <intent-filter> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.BROWSABLE"/> <data android:scheme="metwd" android:host="oauthtoken"/> </intent-filter> </activity>

हमने "oauthtoken" छद्म-मेजबान के लिए "मेटवार्ड" प्रोटोकॉल हैंडलर के रूप में AuthTokenActivity पंजीकृत किया। अब यह कॉलबैक यूआरआई metwd://oauthtoken को निर्दिष्ट करने के लिए पर्याप्त है metwd://oauthtoken पंजीकृत एप्लिकेशन की सेटिंग में metwd://oauthtoken , और उपयोगकर्ता के सफल OAuth प्राधिकरण के बाद AuthTokenActivity कहा जाएगा। इस गतिविधि में, आपको प्राप्त स्ट्रिंग को पार्स करने की जरूरत है और साझाकरण में टोकन को बचाने की आवश्यकता है:

 String fragment = getIntent().getData().getFragment(); String[] parts = fragment.split("\\&"); for (String part : parts) { if (part.startsWith("access_token=")) { String token = part.substring(param.length(), part.length()); //     preferences getSharedPreferences(Globals.PREF_FILE, 0) .edit() .putString(Globals.PREF_TOKEN, token) .commit(); } }

डेटा पुनर्प्राप्ति

विजेट के लिए डेटा पुनर्प्राप्ति कोड अत्यंत सरल है:

 MetrikaApi api = Globals.getApi(context); //    Metrika API Report report = api.makeReportBuilder(Reports.trafficSummary, counterId) .withDateFrom(new MetrikaDate()) .withDateTo(new MetrikaDate()) .build(); return new Result(report.getTotals().getInt("visits"));

बारीकियों यह है कि इस कोड को "हेड-ऑन" निष्पादित नहीं किया जा सकता है। Metrica API सर्वर बहुत तेज़ी से प्रतिक्रिया करते हैं, लेकिन HTTP अनुरोध स्वयं सर्वर पर वापस जा सकता है और धीमी और अविश्वसनीय मोबाइल संचार चैनलों के माध्यम से वापस आ सकता है। नतीजतन, एंड्रॉइड ओएस के दृष्टिकोण से एक प्रतिक्रिया का इंतजार करने वाले विजेट को "फ्रीज" किया जाएगा, और एक विंडो प्रदर्शित की जाएगी जो यह दर्शाता है कि निलंबित एप्लिकेशन क्रैश। यह स्पष्ट रूप से वह नहीं है जिसकी हमें आवश्यकता है। इसलिए, मैट्रिक्स एपीआई के सभी अनुरोधों को एसिंक्रोनस क्लास का उपयोग करके अतुल्यकालिक रूप से निष्पादित किया जाता है। यहाँ काउंटर सूची लोड करने के लिए सरलीकृत कोड है (पूरा संस्करण विजेटसेटअप क्लासिटी में है ):

 private class CountersLoadTask extends AsyncTask<Void, Void, Counter[]> { private ProgressDialog progressDialog; protected void onPreExecute() { progressDialog = ProgressDialog.show(...); } protected void onPostExecute(Counter[] counters) { progressDialog.dismiss(); counterList.addAll(Arrays.asList(counters)); //  ,      listAdapter.notifyDataSetChanged(); } protected Counter[] doInBackground(Void... voids) { return Globals.getApi(WidgetSetupActivity.this).getCounters(); } }

विजेट के लिए, डेटा के साथ काम करना थोड़ा अधिक जटिल है। शुरू करने के लिए, विजेट प्रदाता जो "विजेट को अपडेट करने का समय" प्राप्त करता है, एंड्रॉइड शब्दावली में, प्रसारण रिसीवर है । प्रसारण रिसीवर का जीवन चक्र छोटा है: यह घटना को संसाधित करता है, जिसके बाद यह तुरंत मर जाता है। यदि आप ईवेंट हैंडलर से एक स्ट्रीम शुरू करते हैं, तो रिसीवर-स्ट्रीम से अपना काम पूरा होने से पहले मर सकता है: उदासी। एंड्रॉइड डेवलपर गाइड ऐसे मामलों के लिए सेवाओं का उपयोग करने की दृढ़ता से अनुशंसा करता है। तो चलिए इसे करते हैं: विजेट प्रदाता ( MetrikaWidgetProvider ) ईवेंट प्राप्त करता है और उन्हें अद्यतन सेवा में प्रसंस्करण के लिए पास करता है। UpdateService , बदले में, AsyncTask माध्यम से अतुल्यकालिक डेटा लोडिंग का उपयोग करता है (अन्यथा, फिर से हमें लंबे समय तक एपीआई से प्रतिक्रिया की प्रतीक्षा में "एप्लिकेशन नॉट रिस्पॉन्सिंग" विंडो मिलती है)।

विजेट प्रदर्शन

एंड्रॉइड में विजेट्स के साथ काम करना एक अलग विषय है जो इस लेख के दायरे से परे है और एंड्रॉइड डेवलपर गाइड और अतिरिक्त लेखों में अच्छी तरह से कवर किया गया है। इसलिए, मैं आपको संक्षेप में बताऊंगा, और विवरण के लिए मैं MetrikaWidgetProvider और UpdateService के स्रोत कोड का उल्लेख UpdateService ।

विजेट तीन अवस्थाओं में हो सकता है: "डेटा प्राप्त", "डेटा अपडेट" और "नो कम्युनिकेशन"। विजेट टाइमर या विजेट पर क्लिक करके अद्यतन किया जाता है।

प्राप्त डेटा विजेट की नियमित स्थिति है जिसमें यह आज के लिए साइट पर विज़िट की संख्या प्रदर्शित करता है। इस स्थिति में, विजेट मानक बार चार्ट - "इंद्रधनुष" को प्रदर्शित करता है, जो कि Yandex.Miprica इंटरफ़ेस के हेडर में दिखाई देता है
डेटा अपडेट एक मध्यवर्ती स्थिति है, जो केवल उपयोगकर्ता की सुविधा के लिए बनाई गई है, ताकि वह विजेट पर एक क्लिक से दृश्य प्रतिक्रिया प्राप्त करे। विजेट एपीआई मेट्रिक में अनुरोध भेजने से पहले विजेट में जाता है, और अनुरोध पूरा होने के बाद बाहर निकल जाता है। इस स्थिति में, एक उलटा "इंद्रधनुष" प्रदर्शित होता है।
कोई संबंध नहीं - यह दर्शाता है कि वर्तमान डेटा प्राप्त नहीं किया जा सकता है। कम संतृप्ति के साथ एक "इंद्रधनुष" के रूप में प्रदर्शित, लगभग ग्रे।

यदि विजेट "नो कनेक्शन" स्थिति में हो सकता है, तो यह अद्यतन करने के लिए तार्किक होगा जब यह कनेक्शन दिखाई देता है ताकि उपयोगकर्ता तुरंत वास्तविक डेटा को देख सके। ऐसा करने के लिए, प्रदाता विजेट नेटवर्क इंटरफ़ेस की स्थिति में बदलाव के साथ जुड़े सिस्टम ईवेंट की सदस्यता लेता है:

 <receiver android:name="ru.metrikawidget.MetrikaWidgetProvider"> <intent-filter> <action android:name="android.appwidget.action.APPWIDGET_UPDATE" /> <action android:name="android.net.conn.BACKGROUND_DATA_SETTING_CHANGED"/> <action android:name="android.net.conn.CONNECTIVITY_CHANGE"/> </intent-filter> ... </receiver>

इस तरह की घटना प्राप्त होने पर, यह देखने के लिए एक चेक बनाया जाता है कि क्या कनेक्शन दिखाई दिया है और एक अद्यतन कहा जाता है:

 if (intent.getAction().equals(ConnectivityManager.CONNECTIVITY_ACTION)) { //     Internet NetworkInfo info = intent.getParcelableExtra(ConnectivityManager.EXTRA_NETWORK_INFO); if (info != null && info.isConnected() && !info.isRoaming()) { //   ,  ,      "offline" ... } }

विजेट स्थापना

एक विजेट MetrikaWidget परियोजना में स्थित स्रोत कोड से संकलित किया जा सकता है।

आप एक Android डेवलपर नहीं हैं, लेकिन एक विजेट का उपयोग करना चाहते हैं? कोई समस्या नहीं है - आप तैयार विजेट डाउनलोड कर सकते हैं। Android Market से रिलीज़ या GitHub के साथ डीबग बिल्ड।

स्थापना के बाद, आपको "Y. Metrika" एप्लिकेशन भी दिखाई देगा, जो वास्तव में विजेट के लिए एक मिनी-निर्देश है।

हम Yandex.Metrica API का उपयोग करके एक विजेट लिख रहे हैं