REST APIでcookieを取り扱う

こんにちは！Marketo大谷です。

今回はREST APIでcookieを取り扱う際のtips的なものを紹介します。

一般的には、Webトラッキング目的のcookieとリードの紐付けは、munchkin.jsの埋め込みやMarketoフォーム、JavaScript APIのassociteLead()などを用いて行われます。他方で、サーバサイドでREST APIを使ってcookieを含むリード情報を登録したい、他システム連携時にマルケトcookieをキーとしてリード情報を投入したい、というような時に、REST APIを使ったcookie情報の書き込みや読み出しを行う必要があります。その際に使うAPIやパラメータ指定時の注意点をいくつか挙げていきます。

1. リード情報取得の際に指定する隠しフィールド名はcookies

リード情報取得系のAPI（Get Lead by Id, Get Leads by Filter Type, Get Leads by List Id等）では、出力するリード属性を fields パラメータで指定できます。email, firstName, lastName等フィールド名を指定するのですが、ここでcookiesと指定すると、リードに紐付いたcookie値を出力することができます。

例えば、以下のようなGet Lead by IdのGETリクエストを投げると、

https://xxx-xxx-xxx.mktorest.com/rest/v1/lead/1055724.json?access_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:ab&fields=email,firstName,lastName,cookies

以下のようにリードに紐づくcookieが取得できます。複数のcookieが紐付いている場合はカンマ区切りで列挙されます。

{
      "requestId": "182b3#15e18b5311d",
      "result": [
          {
              "id": 1055724,
              "lastName": null,
              "email": "kjashaedd-2@klooblept.com",
              "cookies": "_mch-marketo.com-1502256040958-xxxxx",
              "firstName": "Kataldar-2"
          }
      ],
      "success": true
}

2. リード情報登録/更新のついでにcookieも登録したい場合にはSync Leadsを使う

次は、REST APIでcookieを登録する方法です。Associate Lead​というその名もずばりのAPIやPush Lead to MarketoというAPIもあるのですが、ここでは一番シンプルなSync LeadsというAPIを紹介します。

例えば、以下のSync LeadsのURLに、

https://xxx-xxx-xxx.mktorest.com/rest/v1/leads.json?access_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:ab

以下のようなリクエストBODYのPOSTリクエストを投げると、

{
   "action": "createOrUdpate",
   "lookupField": "email",
   "input": [
     {
       "email": "kjashaedd-1@klooblept.com",
       "firstName": "Kataldar-1",
       "cookies": "_mch-marketo.com-xxxxxxxxxxxxxx-xxxxx"
     },
     {
       "email": "kjashaedd-2@klooblept.com",
       "firstName": "Kataldar-2",
       "cookies": "_mch-marketo.com-yyyyyyyyyyyyyy-yyyyy"
     }
   ]
}

リードの新規追加もしくは更新の際にcookieの登録も行われます。ここでのポイントは2つです。

• cookieを登録するフィールド名はcookies
• cookieとして登録する値は 実際のcookieの値のうち赤字の部分  id:xxx-xxx-xxx&token:_mch-xxxx.com-xxxxxxxxxxxxx-xxxxx

なお、実はCSVファイルのbulk importでもcookiesフィールドを指定するとcookieを登録可能です。

（2017/11/10 追記）

Associate Lead​以外のAPIでcookieを登録する場合、当該cookieに紐付いて蓄積された匿名リード時代のアクティビティがマージされない点にはご注意ください。リードを登録した上で匿名時のアクティビティのマージしたい場合は、リード生成後にAssociate Leadを行う必要があります。詳しくはこちらの記事を参照してください。

というわけで、今回は以上です。是非試してみてください。