Yahoo!広告スクリプト | Developer Center

オーディエンスリスト（顧客データ）の自動アップロード

更新履歴

2024/07/24　スクリプトをV202406版に対応、機能強化
　　　　　　　コピーボタン・目次追加などのレイアウト変更

スクリプトの概要

ディスプレイ広告では、広告主様が保有している顧客データのファイルをアップロードして、オーディエンスリストにインポートできます。
Yahoo!広告スクリプトでは、このインポート作業を自動化できます。自動アップロードを利用することで、常に最新のデータを活用することができます。

インポートファイルの作成について

インポートファイルの作成方法については、こちらのヘルプをご覧ください。

本ページでは、オーディエンスリスト（顧客データ）を自動でアップロードするスクリプトを以下の２パターンご紹介します。
パターン１：Googleドライブ上に置いたファイルから自動でアップロードする場合
パターン２：Googleスプレッドシートからアップロードする場合

ご利用の流れ

1. Yahoo!広告スクリプトとGoogleアカウントを連携します

　詳しくはGoogleアカウントとの連携を確認してください。
　※すでに連携済みの方は次のステップからご設定ください。

2.パターンごとに、以下の準備をしてください。 　

　パターン１：Googleドライブ上のファイルからアップロードする場合
　　(1) Googleドライブにオーディエンスリスト（顧客データ）インポート用のファイルをアップロードします
　　　オーディエンスリスト（顧客データ）インポート用のファイルの仕様は、こちらのヘルプをご確認ください。
　　(2) Googleドライブにアップロードした対象のファイルIDを取得します
　　　詳しくはGoogleドライブのファイルIDの取得方法をご確認ください。

　パターン２：Googleスプレッドシートからアップロードする場合
　　(1) GoogleスプレッドシートのA列に、下記のように顧客データを記載します（以下の例はaaid）
　　
　　(2) (1)のスプレッドシートIDを取得します
　　　詳しくはGoogleスプレッドシートIDの取得方法をご覧ください。

3.管理画面上のスクリプト作成画面にて、本ページに後述のサンプルコードを設定してください。

　※スクリプトの新規作成および編集の手順はこちらをご覧ください。

4.管理画面上にてスクリプトの設定を完了後、スクリプトの実行頻度の設定をしてください。
　※スクリプトの実行頻度の設定手順はこちらをご覧ください。

サンプルコード内各定数のご説明

後述のサンプルコードにおける各定数の設定方法についてご説明いたします。

■オーディエンスリストID

管理画面でオーディエンスリストIDを確認し、指定します。

const AUDIENCE_LISTID = 1234567890;

※オーディエンスリストIDの確認についての詳細はこちらのヘルプをご覧ください

■ファイルID（Googleドライブ上のファイルからアップロードする場合のみ）

「ご利用の流れ」の手順2で取得したファイルIDを指定します。

const FILE_ID = '11111AAAAAbbbbb_-222222BBBBBccccc';

■圧縮タイプ（Googleドライブ上のファイルからアップロードする場合のみ）

Googleドライブ上に格納したファイルが圧縮なし（通常のcsvファイル）の場合は「NONE」、ZIP形式で圧縮している場合は「ZIP」を指定してください。

const COMPRESS_TYPE = 'NONE';

■スプレッドシートの設定（Googleスプレッドシートからアップロードする場合のみ）

「ご利用の流れ」の手順2で取得したスプレッドシートID、シート名を指定します。

設定する定数	設定方法
const SPREAD_SHEET_ID = 'SPREAD_SHEET_ID';	スプレッドシートIDを '（半角シングルクオーテーション）の間に記載
const SHEET_NAME = 'SHEET_NAME';	シート名を '（半角シングルクオーテーション）の間に記載

■アップロード種別

初期値は「MAIL_ADDRESS_AND_PHONE_NUMBER（ハッシュ化メールアドレスまたは電話番号）」となっています。

const UPLOAD_TYPE = 'MAIL_ADDRESS_AND_PHONE_NUMBER';

必要に応じて、「MAIL_ADDRESS_AND_PHONE_NUMBER」の部分を以下の設定値に変更してください。

設定値	説明
IDFA	iOS端末用広告識別子です。
AAID	Android端末用広告識別子です。
MAIL_ADDRESS_AND_PHONE_NUMBER	ハッシュ化メールアドレスまたは電話番号です。 ※管理画面でのアップロードと異なり、Yahoo!広告スクリプト経由ではハッシュ化は必須です。メールアドレスと電話番号のハッシュ化の詳細はヘルプを参照してください。

■実行結果のメール/Slack通知

実行結果をメールまたはSlackで通知する場合、定数の設定方法の詳細はこちらをご覧ください。

サンプルコード

下記のスクリプトを、「コピー」ボタンを押してコピーし、スクリプトの入力画面に貼り付けてください。（このとき、灰色のコメント部分は消さずに残しておいてください）
「サンプルコード内各定数のご説明」またはスクリプト内に記載の利用方法に沿って、設定が必要な定数を設定してください。

パターン１：Googleドライブ上のファイルからアップロードする場合


/*
■スクリプト内容
指定したGoogleドライブのファイルから、オーディエンスリスト（顧客データ）をアップロードします。
■利用方法
１．当スクリプトを、ディスプレイ広告のスクリプトとしてください。
２．定数を以下のように設定してください。
■定数
・AUDIENCE_LISTID：管理画面上でオーディエンスリストIDを確認して指定
・FILE_ID：Googleドライブ上のファイルIDを指定
・UPLOAD_TYPE：IDFA、AAID、MAIL_ADDRESS_AND_PHONE_NUMBERの3つが利用できます。詳細はこちら→https://ads-developers.yahoo.co.jp/ja/ads-script/product-guide/reference/enums/display.AudienceListServiceUploadUserListUploadType.html
・COMPRESS_TYPE：圧縮なしの場合は「NONE」、ZIP形式で圧縮している場合は「ZIP」
・FLAG_MAIL：結果をメール送信するならtrue、しないならfalse
・MAIL_TO：メール送信先のYahoo! BusinessID
・MAIL_TITLE：メールタイトル
・FLAG_SLACK：結果をSlack送信するならtrue、しないならfalse
・URL_FETCH_APP：SlackのWebhook URL
*/
//設定が必要な定数
const AUDIENCE_LISTID = 1234567890;
const FILE_ID = '11111AAAAAbbbbb_-222222BBBBBccccc';
const UPLOAD_TYPE = 'MAIL_ADDRESS_AND_PHONE_NUMBER';
const COMPRESS_TYPE = 'NONE';
const FLAG_MAIL = false;
const MAIL_TO = ['Yahoo! JAPAN Business ID'];
let MAIL_TITLE = 'オーディエンスリスト自動アップロード';
const FLAG_SLACK = false;
const URL_FETCH_APP = 'SLACK_WEBHOOK_URL';
//設定が不要な定数（変更するとエラーになります）
const accountId = AdsUtilities.getCurrentAccountId();
let TEXT_MESSAGE_ARRAY = [];
function main() {
  try {
    const fileData = DriveApp.getFileById(FILE_ID).getBlob().getBytes();
    let uploadList = Display.AudienceListService.uploadUserList(accountId, AUDIENCE_LISTID, UPLOAD_TYPE, COMPRESS_TYPE, fileData).rval;
    if (uploadList.values[0].operationSucceeded) {
      sendMailAndSlack('オーディエンスリストの自動アップロードが完了しました。');
    } else {
      throw new Error('アップロード時にエラーが発生しました');
    }
  } catch (error) {
    MAIL_TITLE = '!!エラー!!' + MAIL_TITLE;
    sendMailAndSlack('オーディエンスリストの自動アップロードでエラーが発生しています！！詳細は管理画面のログをご確認ください。\n' + error);
  }
}
function sendMailAndSlack(text) {
  logAndMessage(text);
  validateAndSendMail();
  validateAndSendSlack();
}
function logAndMessage(text) {
  Logger.log(text);
  TEXT_MESSAGE_ARRAY.push(text);
}
function validateAndSendMail() {
  if (FLAG_MAIL) {
    if (MAIL_TO.length < 1 || !MAIL_TO.every(str => typeof str === 'string' && /^[a-zA-Z0-9]+$/.test(str))) {
      throw new Error('Yahoo! JAPANビジネスIDを設定してください。メール送信前までに実行された処理は完了しています。');
    }
    MailApp.sendEmail({
      to: MAIL_TO,
      subject: MAIL_TITLE,
      body: TEXT_MESSAGE_ARRAY.join('\n')
    });
  }
}
function validateAndSendSlack() {
  if (FLAG_SLACK) {
    if (URL_FETCH_APP === 'SLACK_WEBHOOK_URL' || URL_FETCH_APP === '') {
      throw new Error('SlackのWebhook URLを設定してください。Slack送信前までに実行された処理は完了しています。');
    }
    UrlFetchApp.fetch(URL_FETCH_APP, {
      method: 'post',
      contentType: 'application/json',
      payload: JSON.stringify({
        text: TEXT_MESSAGE_ARRAY.join('\n'),
      }),
    });
  }
}

パターン２：Googleスプレッドシートからアップロードする場合


/*
■スクリプト内容
指定したGoogleスプレッドシートから、オーディエンスリスト（顧客データ）をアップロードします。
■利用方法
１．当スクリプトを、ディスプレイ広告のスクリプトとしてください。
２．定数を以下のように設定してください。
■定数
・AUDIENCE_LISTID：管理画面上でオーディエンスリストIDを確認して指定
・SPREAD_SHEET_ID　//スプレットシートIDを指定
・SHEET_NAME //スプレッドシートのシート名
・UPLOAD_TYPE：IDFA、AAID、MAIL_ADDRESS_AND_PHONE_NUMBERの3つが利用できます。
              詳細はこちら→https://ads-developers.yahoo.co.jp/ja/ads-script/product-guide/reference/enums/display.AudienceListServiceUploadUserListUploadType.html
・FLAG_MAIL：結果をメール送信するならtrue、しないならfalse
・MAIL_TO：メール送信先のYahoo! BusinessID
・MAIL_TITLE：メールタイトル
・FLAG_SLACK：結果をSlack送信するならtrue、しないならfalse
・URL_FETCH_APP：SlackのWebhook URL
*/
//設定が必要な定数
const AUDIENCE_LISTID = 1234567890;
const SPREAD_SHEET_ID = 'SPREAD_SHEET_ID';
const SHEET_NAME = 'SHEET_NAME'
const UPLOAD_TYPE = 'MAIL_ADDRESS_AND_PHONE_NUMBER';
const FLAG_MAIL = false;
const MAIL_TO = ['Yahoo! JAPAN Business ID'];
let MAIL_TITLE = 'オーディエンスリスト自動アップロード';
const FLAG_SLACK = false;
const URL_FETCH_APP = 'SLACK_WEBHOOK_URL';
//設定が不要な定数（変更するとエラーになります）
const accountId = AdsUtilities.getCurrentAccountId();
let TEXT_MESSAGE_ARRAY = [];
function main() {
  try {
    const ss = validateAndGetSpreadsheet();
    const sh = validateAndGetSheet(ss);
    let ssDataArray = sh.getDataRange().getValues();
    let fileContent = '';
    ssDataArray.forEach(row => {
      fileContent += row[0] + '\n';
    });
    //スプレッドシートは圧縮なし・v14以降そのままUPでOK
    let uploadList = Display.AudienceListService.uploadUserList(accountId, AUDIENCE_LISTID, UPLOAD_TYPE, 'NONE', fileContent).rval;
    if (uploadList.values[0].operationSucceeded) {
      sendMailAndSlack('オーディエンスリストの自動アップロードが完了しました。');
    } else {
      throw new Error('アップロード時にエラーが発生しました');
    }
  } catch (error) {
    MAIL_TITLE = '!!エラー!!' + MAIL_TITLE;
    sendMailAndSlack('オーディエンスリストの自動アップロードでエラーが発生しています！！詳細は管理画面のログをご確認ください。\n' + error);
    throw error;//管理画面上でエラーになるよう再スロー
  }
}
function validateAndGetSpreadsheet() {
  if (SPREAD_SHEET_ID === 'SPREAD_SHEET_ID' || SPREAD_SHEET_ID === '') {
    throw new Error('スプレッドシートIDを設定してください。');
  }
  try {
    return SpreadsheetApp.openById(SPREAD_SHEET_ID);
  } catch (e) {
    throw new Error('スプレッドシートを開くことが出来ませんでした。スプレッドシートIDまたはスプレッドシートの権限が正しいか確認してください。' + e);
  }
}
function validateAndGetSheet(ss) {
  if (SHEET_NAME === '') {
    throw new Error('シート名を設定してください。');
  }
  const sh = ss.getSheetByName(SHEET_NAME);
  if (sh === null) {
    throw new Error('シートが開けませんでした。シート名を確認してください。');
  }
  return sh;
}
function sendMailAndSlack(text){
  logAndMessage(text);
  validateAndSendMail();
  validateAndSendSlack();
}
function logAndMessage(text) {
  Logger.log(text);
  TEXT_MESSAGE_ARRAY.push(text);
}
function validateAndSendMail() {
  if (FLAG_MAIL) {
    if (MAIL_TO.length < 1 || !MAIL_TO.every(str => typeof str === 'string' && /^[a-zA-Z0-9]+$/.test(str))) {
      throw new Error('Yahoo! JAPANビジネスIDを設定してください。メール送信前までに実行された処理は完了しています。');
    }
    MailApp.sendEmail({
      to: MAIL_TO,
      subject: MAIL_TITLE,
      body: TEXT_MESSAGE_ARRAY.join('\n')
    });
  }
}
function validateAndSendSlack() {
  if (FLAG_SLACK) {
    if (URL_FETCH_APP === 'SLACK_WEBHOOK_URL' || URL_FETCH_APP === '') {
      throw new Error('SlackのWebhook URLを設定してください。Slack送信前までに実行された処理は完了しています。');
    }
    UrlFetchApp.fetch(URL_FETCH_APP, {
      method: 'post',
      contentType: 'application/json',
      payload: JSON.stringify({
        text: TEXT_MESSAGE_ARRAY.join('\n'),
      }),
    });
  }
}

結果確認

広告管理画面からオーディエンスリストを確認した際、「ユーザーサイズ」にアップロードした件数が反映されていれば完了です。

ヒント

オーディエンスリストを作成した後、ユーザーサイズが確認できるまで最大で48時間程度かかる場合があります。

管理画面の例

Developer Center

Yahoo!広告 スクリプト | Developer Center