RubyからGoogle Analytics API を扱う"Legato"の使い方

Legatoの使い方をかんたんにメモします。

LegatoはGoogle Analytics API を扱うためのライブラリです。以前メジャーだった今はメンテナンスされていないGarbとコンパチブルです。

通常データの取り扱い（コアレポーティングAPI）

Legatoを使うとRuby的にGoogleAnalyticsのデータを取り扱えます。

以下クラスはAPI経由で取得するデータの定義です。metricsが指標で、dimensionsがデータの取得軸です。dimensionsによって分割されたデータが返ってきます。

    class OrganicKeyword
      extend Legato::Model

      metrics :sessions, :bounces, :bounceRate, :exits, :exitRate, :pageviews, :screenviews
      dimensions :channelGrouping, :keyword

      filter :keywords_contain, &lambda {|keywords|
        keywords.map{|keyword|
          contains(:keyword, keyword)
        }
      }
      filter :only_organic, &lambda {
        eql(:channelGrouping, "Organic Search")
      }
    end

以下のコードでは、検索エンジン経由でかつ、keywordsが含まれるアクセス解析データがrowsに返され、さらにそれをkeywordとセッション数がペアになったマップに格納しています。

rows = OrganicKeyword.only_organic.keywords_contain(keywords).results(profile, options)
map = rows.inject({}){|result, v|
  result[v.keyword] = v.sessions
  result
}

###ソートの方法

この部分がちょっと分かり辛かったので説明します。

セッション数の大きい順でソートするには以下のように先頭に"-"ハイフンを付けます。

results(start_date: 7.days.ago, end_date: Time.now, sort: "-sessions")

複数の検索条件を指定する場合、配列にして渡します。以下のコードはコンバージョンの多かった順でのソートを優先します。

results(start_date: 7.days.ago, end_date: Time.now, sort: ["-goalCompletionsAll", "-sessions"])

###フィルタリングの方法

Legatoを使ったfilterのAND検索とOR検索が少し分かりづらかったので、この説明をします。

以下AND検索の例です。

filter :for_keyword, &lambda {|v| contains(:keyword, v)}
OrganicKeyword.for_keyword("Qiita").for_keyword("Ruby") # AND検索

以下OR検索の例です。mapにして値を返しているのがポイントです。これらは全てORで繋がれて検索で利用されます。

filter :for_keyword, &lambda {|keywords|
        keywords.map{|keyword|
          contains(:keyword, keyword)
        }
      }
OrganicKeyword.for_keyword(["Qiita", "Ruby"]) # OR検索

OR検索の方法として、以下のように|(パイプ)で単語を繋ぐ方法もあります。この場合、つないだ文字が長くなるとGoogleAnalyticsのフィルタ指定可能な上限文字数の128文字を超えやすくなるので注意が必要です。

filter :for_keyword, &lambda {|v1, v2| contains(:keyword, "#{v1}|#{v2}")}
OrganicKeyword.for_keyword("Qiita", "Ruby") # OR検索

Filter Expressionsの正規表現についての箇所に128文字超えると400 Bad Requestをサーバーから返すとありました。https://developers.google.com/analytics/devguides/reporting/core/v3/reference#filterExpressions

Legatoのフィルタリングで正規表現を使うには#contains を使う必要があります。他に使えそうなものとして#substring がありますが、こちらは正規表現が使えません。この理由はGoogleAnalyticsのフィルタで使うOperatorの指定にあります。

以下はLegatoのメソッドとオペレータと、GoogleAnalyticsフィルタリングのオペレーターとdescriptionを組み合わせたものです。#containsと#does_not_containに正規表現が使える事が分かりますね。

matches          => '==', # Exact match
does_not_match   => '!=', # Does not match
contains         => '=~', # Contains a match for the regular expression
does_not_contain => '!~', # Does not match regular expression
substring        => '=@', # Contains substring
not_substring    => '!@'  # Does not contain substring

マルチチャネルの取り扱い

Legatoでは以下のようにCore Reporting APIと同じ感覚でMulti-Channel Funnels Reporting API (MCFレポーティングAPI) を扱えます。{tracking_scope: :mcf}とつけてあげるのがポイントになります。

    class MultiFunnel
      extend Legato::Model

      metrics :firstImpressionConversions,
      :impressionAssistedConversions,
      :totalConversions,
      :assistedConversions,
      :firstInteractionConversions,
      :lastInteractionConversions,
      {tracking_scope: :mcf}

      dimensions :basicChannelGroupingPath,
      :keywordPath,
      :sourceMediumPath,
      {tracking_scope: :mcf}
    end

マルチチャネルでは、ウェブサイトで起こったコンバージョンを経路別で分析したり、アシストCVの取得が出来ます。

リファレンスへのリンク集

Legato
https://github.com/tpitale/legato

Legatoのフィルタリング説明
https://github.com/tpitale/legato/wiki/Filtering

コアレポーティングAPIのリファレンス
https://developers.google.com/analytics/devguides/reporting/core/v3/reference

コアレポーティングAPIのソート説明箇所
https://developers.google.com/analytics/devguides/reporting/core/v3/reference#sort

マルチチャネルの概要
https://support.google.com/analytics/answer/1191180

MCFレポーティングAPIのリファレンス
https://developers.google.com/analytics/devguides/reporting/mcf/v3/