Yandex.Metrica APIを使用してウィジェットを作成しています

少し前まで、Yandex.Metricaは、独自のプログラムからMetricaのほぼすべての機能にアクセスできるオープンAPIを発表しました 。
今日は、このAPIの使用と、それに基づいてAndroidデバイス用のシンプルなウィジェットを作成する方法について少しお話したいと思います。

APIの基本

Yandex.Metrica APIはRESTの原則に基づいて構築されています。 APIを介して制御できるすべては、カウンター、目標、フィルターなどのリソースで表されます。 リソースの操作（読み取り、削除、変更）は、I.Metrica APIサーバーへのHTTPリクエストによって実行され、各タイプの操作には独自のHTTPメソッドがあります。

• GET：コンテンツの読み取り
• POST：リソースの追加
• PUT：リソースの変更
• DELETE：リソースを削除します

たとえば、カウンターのリストを取得するには、カウンターリソースGET /countersを参照する必要がありGET /counters 。 1つのカウンターに関する情報を取得するには、その識別子でリソースを参照します： GET /counter/{id} 。 削除するには、同じリソースを参照しますが、DELETEメソッドを使用します： DELETE /counter/{id} 。

REST呼び出しの入力と結果は、XMLとJSONの2つの形式でエンコードできます。 将来的には、プログラミング言語で使用される構造に表示するための、よりコンパクトで便利な形式としてJSONを使用します。

当然、APIを使用した作業は、Y。Metrikaアカウントからアクセスされるカウンターでのみ可能です。 OAuth認証は、アカウント所有者を識別するために使用されます。 とてもシンプルに配置されています。 Yandex.Metrica APIを使用する開発者は、アプリケーションを登録し（ 手順を参照）、アプリケーション識別子を受け取ります。 アプリケーションを登録した後、アプリケーション用のデバッグOAuthトークンを取得し、Metrica APIの操作をすぐに開始できます。 デバッグトークンを使用すると、アプリケーションを登録した開発者アカウントから利用可能なカウンターを操作できます。 トークンは、URLの追加パラメーター（ ...&oauth_token=<acces_token> ）として、またはHTTP要求Authorization: OAuth <access_token> ...&oauth_token=<acces_token>のヘッダーとして、各HTTP要求で送信する必要があります。

開発者が利用できるカウンターだけでなく、アプリケーションが任意のカウンターで動作するためには、アプリケーションユーザーごとに個別のOAuthトークンが必要です。 どうすれば入手できます：

1. 最も安全な方法は、アプリケーションによってユーザーが特別なYandexページにリダイレクトされてログインし、（まだそうしていない場合）カウンターへのアクセスをアプリケーションに与えることです。 その後、ユーザーはアプリケーションにリダイレクトされ、リダイレクト先のURLには、このユーザーのOAuthトークンを含むパラメーターが含まれます。 アプリケーションはこのパラメーターを読み取り、トークンを記憶する必要があります。 この手順の詳細は、 マニュアルに記載されています 。
2. アプリケーションは、ユーザーからユーザー名とパスワードを直接要求し、それらをYandexサーバーのOAuthに渡し、応答でトークンを受信することにより、トークンを受信することもできます。 この方法は安全性が低くなります。ログインとパスワードが明示的に要求および送信されます。

RESTを使用することにより、APIを使用した最も簡単な操作（読み取り要求）が、コーディングなしでブラウザーから直接可能になります。 たとえば、 このリクエストでは、I.Metrica APIのデモアカウントのカウンターに関する情報が表示されます。 このような要求は、カウンターの出席に関するレポートを作成します。

RESTインターフェースは単純ですが、高級言語で書かれたプログラムでAPIを完全に使用するには、リクエストURLの生成、HTTPリクエストの送信と結果の受信、JSONの生成と解析、エラー処理など、非常に多くのジェスチャーを実行する必要があります。 私の人生を簡素化するために、JavaのI. Metrics APIを操作するための既製のライブラリMetrika4jを作成しました 。 ライブラリコードはApacheライセンスの下で配布されます。必要に応じて自由に変更および補足できます。 次に、このライブラリを使用して、サイトトラフィックを表示するAndroidデバイス用のウィジェットを作成する方法を説明します。

メトリカ4j

Metrika4jを使用すると、Yandex.Metricaを使用して、おなじみのJavaの概念（クラス、関数呼び出し、型）を操作し、HTTPおよびJSONでの低レベルの作業を考慮する必要がなくなります。 ライブラリの中心的なインターフェースはMetrikaApiです。 メトリックの主要エンティティであるカウンターとレポートを操作するメソッドがあります。 追加のエンティティ（目標、フィルターなど）の操作は、メインのMetrikaApiクラスから取得した個別のミニAPIで行われます。

メソッドの構造は、I。Metrica APIへのREST呼び出しの構造にほぼ対応しています。 REST呼び出しに渡される引数は、APIメソッドに渡される引数に対応します（レポートAPIを除きます。これについては別途説明します）。
Metrika4jは、JSONを操作するための標準の2つのライブラリ、 Jackson JSONプロセッサとorg.jsonをサポートしています。 ジャクソンの場合、org.jsonの機能の100％がサポートされます。これは、レポートを操作するために最低限必要なものです。カウンターのリストを読み取り、レポートを受信します。 org.jsonライブラリーはAndriod APIに組み込まれているため、Androidアプリケーションに便利です。 必要に応じて、開発者は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を介して利用できます。 使用可能なレポートのセットは、 Reportsクラスに含まれています。 選択したレポートを作成するには、 MetrikaApi.makeReportBuilder(Reports report, int counterId)メソッドMetrikaApi.makeReportBuilder(Reports report, int counterId)呼び出す必要があります。 MetrikaApi.makeReportBuilder(Reports report, int counterId)メソッドは、特別なオブジェクトであるReportBuilderレポートビルダーを返します。 レポートビルダーで、必要なレポートパラメーター（時間間隔、並べ替えなど）を設定する必要があります。 すべてのパラメーターが設定されたら、 ReportBuilder.build()メソッドを呼び出します。このメソッドはHTTP要求をMetrics APIに送信し、レポートを返します。

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

レポートは、結果といくつかの追加情報（合計、レポートが関連する日付範囲など）を含む表であるReportオブジェクトの形式で返されます。 結果テーブルの各行はReportItemオブジェクトであり、データはgetXXX(String fieldName)メソッドの1つを使用して取得できます（JDBCを使用する場合、 ResultSetから値を取得するのに似ています）。 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の操作の詳細な説明は、 Javadocにあります。

アンドロイド用ウィジェット

Yandex.MetricaやMetrika4j APIなどの強力なツールを自由に使用できるため、Yandex.Metricaの代替ユーザーインターフェイスを作成するまで、あらゆる問題を解決できます。 ただし、この記事の枠組みの中で、より控えめな目標に限定します。つまり、サイトへの現在のトラフィックを表示するAndroid用のウィジェットを作成します。 ウィジェットのソースコードは、 MetrikaWidgetプロジェクトのGitHubで入手できます。 Metrika4jコードと同様に、最小限のライセンス制限で自由に配布されます。

OAuth認証

MetrikaApiと認証を作成することから始めましょう。 アプリケーションは1つのアカウントのみで機能するため、 MetrikaApiインスタンスをシングルトンにできます。 そのコードは、 Globalsクラスに含まれています。

 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トークンがまだSharedPreferencesにない場合は、取得する必要があります。 これを行うには、トークンリクエストURLにアクセスします。

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

ユーザーにとっては、開いたページのようになります。「アプリケーションはYandexのデータへのアクセスを要求しています。」 ユーザーが正常にログインし、アクセスを許可したと想定します。 次に、楽しみが始まります。トークンをWebインターフェースからアプリケーションに転送する方法は？ これを行うには、アプリケーションのアクティビティの1つを、アプリケーションに固有のプロトコルのハンドラーとして登録する必要があります（ハンドラーが他のアプリケーションと重複しないように特定します）。 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」擬似ホストの「metwd」プロトコルハンドラとしてAuthTokenActivityを登録しました 。 これで、登録済みアプリケーションの設定でコールバックURI metwd://oauthtokenを指定するだけで十分です。ユーザーのOAuth認証が成功すると、 AuthTokenActivityが呼び出されます。 このアクティビティでは、受信した文字列を解析し、S​​haredPreferencesにトークンを保存する必要があります。

 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要求自体はサーバーに送られ、低速で信頼性の低いモバイル通信チャネルを経由して戻ることができます。 その結果、応答を待っているウィジェットはAndroid OSの観点から「フリーズ」し、中断されたアプリケーションがクラッシュすることを示唆するウィンドウが表示されます。 これは明らかに必要なものではありません。 したがって、Metrics APIへのすべてのリクエストは、 AsyncTaskクラスを使用して非同期的に実行されます。 カウンターリストを読み込むための簡略化されたコードは次のとおりです（フルバージョンはWidgetSetupActivityクラスにあります）。

 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(); } } 

ウィジェットの場合、データの操作はもう少し複雑です。 まず、「ウィジェットを更新する時間」イベントを受け取るウィジェットプロバイダーは、Android用語ではブロードキャストレシーバーです。 放送受信機のライフサイクルは短く、イベントを処理し、その後すぐに死にます。 イベントハンドラーからストリームを開始すると、ストリームの処理が完了する前にレシーバーaが停止する場合があります。悲しみです。 Android開発者ガイドでは、このような場合にサービスを使用することを強くお勧めします。 それでは、ウィジェットプロバイダー（ MetrikaWidgetProvider ）がイベントを受け取り、それらをUpdateServiceに処理するために渡します 。 次に、 UpdateService 、 AsyncTaskを介した非同期データの読み込みを使用します（それ以外の場合は、APIからの応答を長時間待機すると、「アプリケーションが応答していません」ウィンドウが表示されます）。

ウィジェット表示

Androidでウィジェットを操作することは、この記事の範囲を超える別の大きなトピックであり、 Android 開発者ガイドと追加の記事の両方で詳しく説明されています。 したがって、簡単に説明します。詳細については、 MetrikaWidgetProvider UpdateServiceとUpdateService ソースコードを参照しUpdateService 。

ウィジェットは、「データ受信」、「データ更新」、「通信なし」の3つの状態になります。 ウィジェットは、タイマーまたはウィジェットをクリックして更新されます。

• 受信したデータは、今日のサイトへのアクセス数を表示するウィジェットの通常の状態です。 この状態では、ウィジェットは標準の棒グラフ-「虹」を表示します。これは、Yandex.Metricaインターフェースのヘッダーに表示されます
• データ更新は中間状態であり、ユーザーの便宜のためだけに作成されるため、ユーザーはウィジェットをクリックすることで視覚的なフィードバックを受け取ります。 ウィジェットは、APIメトリックにリクエストを送信する前にウィジェットに入り、リクエストが完了すると終了します。 この状態では、反転した「虹」が表示されます。
• 接続なし -現在のデータを取得できなかったことを示す状態。 彩度が低く、ほぼ灰色の「虹」として表示されます。

ウィジェットが「接続なし」状態になる可能性がある場合、ユーザーが実際のデータをすぐに見ることができるように、この接続が表示されたときにウィジェットを更新することは論理的です。 これを行うために、プロバイダーウィジェットは、ネットワークインターフェイスのステータスの変化に関連するシステムイベントをサブスクライブします。

 <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マーケットからリリースするか、 GitHubでデバッグビルドします 。



インストール後、「Y。Metrika」アプリケーションも表示されます。これは、実際にはウィジェットのミニインストラクションです。