タグマネージャmatomo APIの使い方

# 概要
**matomo**のタグマネージャーのAPIの使い方を記載します。
一般的なWeb APIの使い方と同じですが、引数が多くややこしいので忘備録です。

# matomoとは
[matomo](https://matomo.org/)はアクセスログ解析のオープンソースです。matomoの機能の一つに**タグマネージャ**があります。
タグマネージャはGoogleタグマネージャが有名ですが、今回はソースコードが公開されているmatomoを使いました。
（多分[Google Tag Manager API](https://developers.google.com/tag-manager/api/v1/?hl=ja)の記事の方が需要高いだろうけど・・・笑）

# タグマネージャとは
ここで言うタグとは**コンバージョンタグ**のことで、HTMLに埋め込んでページビューなどの計測をすることができます。
**タグマネージャ**は、コンバージョンタグを管理するためのツールです。
インターネット広告やSEO関連など、Webマーケティング業界で主に使われています。

[タグとは｜5分でわかるタグの基本](https://liskul.com/st-what-is-tag-8639)
[今さら聞けない、タグマネジメント入門基礎の基礎 - Content Hub（コンテンツハブ） | ナイル株式会社](https://cont-hub.com/blog/03/356/)

# matomo API
[公式ドキュメント](https://developer.matomo.org/api-reference/reporting-api)からAPIメソッド一覧を確認できます。
タグマネージャのメソッド一覧は[こちら](https://developer.matomo.org/api-reference/reporting-api#TagManager)です。

## 検証環境

- [matomo:3-apache](https://hub.docker.com/_/matomo)
- [mysql:5.7](https://hub.docker.com/_/mysql)

## メソッドの説明
API共通で指定が必要な引数(パラメータ)は以下の通りです。詳しくは[公式ドキュメント](https://developer.matomo.org/api-reference/reporting-api)をご確認ください。

- idSite
- period
- date
- segment
- format
- filter_limit
- token_auth

今回は**トリガー作成**と**タグ作成**のみ取り上げます。
実際の管理画面を見ながらだと何の値か理解しやすいです。
管理画面で入力必須のものはAPIでも入力必須です。

管理画面から作成したトリガーやタグをgetContainerTriggers/Tagsメソッドをたたいて実際の値を確認するのも良いと思います。

#### TagManager.addContainerTrigger 

トリガーを作成するメソッドです。
引数は以下のようになります。

- idSite : WebsiteのID
- idContainer : コンテナのID
- idContainerVersion : コンテナバージョンのID
- type : トリガーのタイプ
- name : トリガーの名前
- parameters : 各トリガー固有のパラメータ
- conditions : トリガーの発火条件

参考：管理画面
<img width="1440" alt="スクリーンショット 2019-07-26 9.38.32.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/140953/d40e8462-b524-b875-3bc6-ce558ee5c6d8.png">

#### TagManager.addContainerTag

タグを作成するメソッドです。
引数は以下のようになります。

- idSite : WebsiteのID
- idContainer : コンテナのID
- idContainerVersion : コンテナバージョンのID
- type : タグのタイプ
- name : タグの名前
- parameters : タグ固有のパラメータ
- fireTriggerIds : 発火するトリガー
- blockTriggerIds : 除外条件のトリガー
- fireLimit : タグ発火の頻度条件
- fireDelay : タグ発火の遅延条件
- priority : タグの優先順位
- startDate : タグの開始日時
- endDate : タグの終了日時

参考：管理画面
<img width="1440" alt="スクリーンショット 2019-07-26 9.37.38.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/140953/880075fe-d322-4ebe-c3e6-1f634d878ab7.png">
<img width="1440" alt="スクリーンショット 2019-07-26 9.38.18.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/140953/438d3ab5-c105-c236-34d8-a69f7aa41611.png">

## PHPからの使用例
PHPからの呼び出し例は[公式](https://developer.matomo.org/guides/querying-the-reporting-api)に記載がありますが、今回はfile_get_contents関数ではなくcurlを使ってAPIを呼び出します。
参考：[APIなどにfile_get_contents()を使うのはオススメしない理由と代替案 - Qiita](https://qiita.com/shinkuFencer/items/d7546c8cbf3bbe86dab8)

トリガー作成とタグ作成のサンプルを以下に書きます。
xxxxの部分は自分のものに置き換えてください。

#### トリガー作成

```add_trigger_sample.php
<?php
$website_id = xxxx;
$container_id = 'xxxx';
$token_auth = 'xxxx';
$base_url = 'http://xxxx/?module=API';

$url = $base_url
    . '&method=TagManager.addContainerTrigger'
    . '&format=json'
    . '&idSite=' . $website_id
    . '&idContainer=' . $container_id
    . '&idContainerVersion=1' //Draft Version
    . '&type=PageView'
    . '&name=api-test3'
    . '&parameters='
    . '&conditions='
    . '&token_auth=' . $token_auth;

$curl = curl_init();
$options = array(
    CURLOPT_URL => $url,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => false,
);
curl_setopt_array($curl, $options);
$response = curl_exec($curl);
$result = json_decode($response, true);

if ($response === FALSE) {
    die(curl_error($curl));
}
curl_close($curl);
```

#### タグ作成

```add_tag_sample.php
<?php
$website_id = xxxx;
$container_id = 'xxxx';
$token_auth = 'xxxx';
$base_url = 'http://xxxx/?module=API';

$url = $base_url
    . '&method=TagManager.addContainerTag'
    . '&format=json'
    . '&idSite=' . $website_id
    . '&idContainer=' . $container_id
    . '&idContainerVersion=' . $draft_container_version_id
    . '&type=CustomHtml'
    . '&name=api-test3'
    . '&parameters[customHtml]=<div></div>'
    . '&parameters[htmlPosition]=bodyEnd'
    . '&fireTriggerIds[0]=1' // $trigger['value']
    . 'block_trigger_ids='
    . 'fire_limit=unlimited'
    . 'priority=' . 999
    . 'fire_delay=' . 0
    . 'start_date=' . null
    . 'end_date=' . null
    . '&token_auth=' . $token_auth;

$curl = curl_init();
$options = array(
    CURLOPT_URL => $url,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => false,
);
curl_setopt_array($curl, $options);
$response = curl_exec($curl);
$result = json_decode($response, true);

if ($response === FALSE) {
    die(curl_error($curl));
}
curl_close($curl);
```

URLが違うだけなので、何度も呼び出す場合はcurl部分をメソッドに切り出すと良いと思います。

## ブラウザからの使用例
Web APIなのでもちろんブラウザからも確認できます。
実装する際にはブラウザからレスポンスを確認しつつ開発するのが良いと思います。

URLでGETリクエストします。
xxxxの部分は自分のものに置き換えてください。

#### トリガー作成

```
http://xxxx/?module=API&method=TagManager.addContainerTrigger&format=json&idSite=xxxx&idContainer=xxxx&idContainerVersion=1&type=PageView&name=api-test&parameters=&conditions=&token_auth=xxxx
```

#### タグ作成

```
http://xxxx/?module=API&method=TagManager.addContainerTag&format=json&idSite=xxxx&idContainer=xxxx&idContainerVersion=1&type=CustomHtml&name=api-test&parameters[customHtml]=<div></div>&parameters[htmlPosition]=bodyEnd&fireTriggerIds[0]=1&block_trigger_ids=&fire_limit=unlimited&priority=999&fire_delay=0&start_date=&end_date=&token_auth=xxxx
```

以上です！