技術情報

データにアノテーション(注釈）を付ける

2015年03月02日 機能説明

※注 この記事は Piwik1.8～2.17のアーカイブ情報です

目次

1. 注釈を作成する目的
2. 注釈の作成と編集
3. アノテーション API

Annotations-700x418

Matomo(Piwik) 1.10 で追加された注釈プラグインにより、注釈メモの作成およびそれを過去のデータに添付することができるようになりました。注釈メモはシンプルなテキストで、書き留めておきたいことはどんなことでもメモしておくことができます。

この機能自体は、一見するとそれほどパワフルには感じられないかもしれません。しかし、このシンプルな機能こそ、あなたのデータに関する理解を深めるのを大いに助けてくれるはずです。

注釈を作成する目的

ウェブサイトを変更する時はいつでも、その変更が複雑かシンプルかに関わらず、Matomo(Piwik) で注釈メモを作成することができます。注釈メモを作成することで、後でそのデータを閲覧し、なぜその変更が行われたのかをあらためて振り返り、貴重なインサイトを得ることができます。

注釈メモの内容は自由に作成できますが、ここでは、注釈機能をスタートするための、いくつかのアイデアをご紹介します:

  • ウェブサイトコンテンツとデザインの変更（新規ブログ投稿、新サイトのデザイン等）
  • E メールニュースレターと E メールマーケティングキャンペーン
  • オフライン広告の開始（紙媒体、ラジオ、テレビ等）
  • プロダクトのローンチのような重要なビジネスマイルストーン
  • 祝祭日のような、カレンダー上の一般的なイベント

上記のように、あなたのウェブサイトやビジネスにとって影響を及ぼす可能性のある出来事や重要なイベントが発生する場合、Matomo(Piwik) に注釈メモを作成しておくと、サイトの訪問にどのような影響があったのかを後で振り返ることができます。

注釈の作成と編集

時間の推移の統計を表示する全てのグラフで注釈を見たり編集したりすることができます。これは、ビジターの概要（ビジター ＞ 概要）、あらゆる目標ページ、参照元概要（参照元 ＞ 概要）、あらゆる推移レポートのポップアップを含みます。

ways_to_access_annotations

日付をクリックすると、具体的な期間（例えば「 2012 年 11 月 15 日」や、「2012 年 11 月 18 日にスタートする週」等）に対する注釈を表示します。
「注釈」リンクをクリックすると、推移グラフにより表示された日付範囲内の全ての注釈を表示します。

annotations_create_new

最後に、注釈メモ（注釈の日付変更も任意能）を入力し、次に保存をクリックします。新規注釈メモが保存されます。

既存の注釈メモを修正するために、まず上部に描かれた注釈ビューワーを開きます。次にログインし、編集したい注釈の隣の「編集」リンクをクリックしてください。もしリンクが表示されていない場合、注釈の編集権限を持っていません。

annotations_edit_links

注）サイトに対する管理アクセス権限を持っている場合、全ての注釈の編集・削除が可能です。

annotations_edit_mode-1024x67

注釈を削除したい場合、「削除」リンクをクリックします。

アノテーション API

UI を通して注釈メモを作成する許可に加えて、アノテーションプラグインもまた、注釈の閲覧、追加、修正を許可するウェブ API を提供します。あなたがプログラマーなら、この API を使っていくつかの興味深いアプリを作ることができます。

まだ作られていないアプリ：

以下は、アノテーション API を使用するアプリのためのアイデアのリストです。これらのアプリは、まだ作成されていませんが、ぜひ作成される日を多くの人が待っています。

  • 変更されるたび、あるいは新規ブログ投稿が書かれるたび、自動的にあなたの Matomo(Piwik) データを注記するワードプレスプラグイン
  • あなたの github アカウントを監視し、コミットまたは新規リリースのたびにあなたの Matomo(Piwik) データを注記するアプリ
  • E メールをあなたの購読者リストに送信するたび、あなたの Matomo(Piwik) データを注記するアプリ

アノテーション API は、Matomo(Piwik) API の一部です。
API がどのように動くかについて詳細はこちらをお読みください。
すでに API がどのように動くかを知っていて、注釈を手で操作するにはそれをどのように使用すべきかを知りたい場合、読み進めてください。

注釈を閲覧するために API を使用する

既存の注釈をリクエストすために使用できる2つの API 手法があります:

1. Annotations.get : 単独の注釈を取得するパラメーター

  • idSite: 注釈が所有するウェブサイトの ID
  • idNote: 注釈の ID

2. Annotations.getAll : 単独の注釈を取得するパラメーター

  • idSite: 検索されるウェブサイトの注釈の ID。 1つ以上の ID が供給される場合、この値はコンマで離される必要があります。
  • date: 注釈が添付されたデータ。または期間が ’範囲’ に設定されている場合、データ範囲
  • period: 使用すべき期間。デフォルトでは、’日付’期間が使用されています。他の値（例えば ’週’ ’月’ ’年’ ’範囲’）を提供する場合、全体の期間内の注釈が返されます。
  • lastN : (任意)もしあれば、最後の N 期間は検索に含まれます。

注釈のカウントにのみ関心がある場合、他の API 手法も利用できます。

Annotations.getAnnotationCountForDates 期間の設定内で注釈のカウントと星印のついた注釈を取得するパラメーター

  • idSite: 注釈をカウントするためのウェブサイトの ID
  • date: 注釈が添付されたデータ。または期間が ’範囲’ に設定されている場合、データ範囲
  • period: 使用すべき期間。デフォルトでは、’日付’ 期間が使用されています。他の値（例えば’週’ ’月’ ’年’ ’範囲’）を提供する場合、全体の期間内の注釈が返されます。
  • lastN: (任意)もしあれば、最後のN期間は検索に含まれます。

注釈の追加と修正のためにAPIを使用する

注釈を作成、修正、削除するために、以下のAPI手法を使用してください。

1. Annotations.add : ウェブサイトと日付に対する新しい注釈を追加するパラメーター

  • idSite: 注釈が追加されているウェブサイトの ID
  • date: 注釈が添付されるべき日付
  • note: 注釈のテキスト
  • starred: (任意) 1または0のいづれか。スター付きとしてこの注釈が始まります。0または何も供給されていない場合は開始されません。

2. Annotations.save : 既存の注釈を修正するパラメーター：

  • idSite: 注釈が属するウェブサイトの ID
  • idNote: 注釈 ID
  • date: (任意)供給されると、既存の注釈の日付は供給された日付に変更されます。
  • note: (任意) 供給されると、既存の注釈のテキストは供給されたテキストに変更されます。
  • starred: (任意) 1または0のいづれか。供給されると、このパラメーターの値に基づいて注釈に星印がつきます。もし1の場合星がつき0の場合はつきません。

3. Annotations.delete : 既存の注釈を削除するパラメーター

  • idSite: 注釈が帰属するウェブサイトの ID
  • idNote: 注釈の ID

Matomo(Piwik) の大部分のリクエスト機能を使ってあなたのアプリ速度を早めます。

作成する予定のアプリが、多くの注釈を作成または修正する場合、大部分の API リクエストを送信したいかもしれません。10 以上の注釈を作成するために 1 つの HTTP リクエストを 1 度に送信することは、多くのリクエストを発行するよりもかなり遅くなります。詳しくはこちらをお読みください。

※この記事はMatomo(Piwik)公式サイト2014年12月14日時点の内容です
※掲載内容が古くなっている場合もありますので最新情報はMatomo(Piwik)公式サイトをご覧ください。

オリジナルの記事はこちら
http://matomo.org/docs/annotations/

技術文書