خدمة AdSense

‫AdSense Management API وإدارة حسابك وتقاريرك على AdSense

تتيح لك خدمة AdSense استخدام AdSense Management API في برمجة تطبيقات Google. تتيح واجهة برمجة التطبيقات هذه لعملاء AdSense الحصول على معلومات حول بنية حساباتهم وإنشاء تقارير حول مستوى أدائها.

هذه خدمة متقدّمة يجب تفعيلها قبل الاستخدام.

مراجع

للحصول على معلومات تفصيلية عن هذه الخدمة، يُرجى الاطّلاع على المستندات المرجعية الخاصة بـ AdSense Management API. مثل جميع الخدمات المتقدّمة في Apps Script، تستخدم خدمة AdSense العناصر والطرق والمعلَمات نفسها التي تستخدمها واجهة برمجة التطبيقات العامة. لمزيد من المعلومات، اطّلِع على كيفية تحديد التواقيع.

للإبلاغ عن المشاكل والعثور على دعم آخر، يمكنك طرح سؤال على Stack Overflow باستخدام العلامة adsense-api.

نموذج التعليمات البرمجية

يستخدِم نموذج الرمز البرمجي التالي الإصدار 2 من واجهة برمجة التطبيقات.

سرد الحسابات

تسرد هذه العيّنة جميع الحسابات المتاحة للمستخدم. يتم تحديد الحسابات كأسماء موارد، مثل accounts/pub-12345، ويمكن استخدامها في طرق أخرى، مثل إدراج عملاء الإعلانات. لاحظ استخدام رموز الصفحات للوصول إلى القائمة الكاملة بالنتائج.

advanced/adsense.gs

عرض على GitHub

/**
 * Lists available AdSense accounts.
 */
function listAccounts() {
  let pageToken;
  do {
    const response = AdSense.Accounts.list({ pageToken: pageToken });
    if (!response.accounts) {
      console.log("No accounts found.");
      return;
    }
    for (const account of response.accounts) {
      console.log(
        'Found account with resource name "%s" and display name "%s".',
        account.name,
        account.displayName,
      );
    }
    pageToken = response.nextPageToken;
  } while (pageToken);
}

عرض قائمة عملاء الإعلانات

تعرض هذه العيّنة جميع عملاء الإعلانات لحساب معيّن. حدِّد الحساب كاسم مورد، مثلاً accounts/pub-12345. يمكنك الحصول على اسم مورد الحساب باستخدام نموذج الرمز النموذجي قائمة الحسابات.

advanced/adsense.gs

عرض على GitHub

/**
 * Logs available Ad clients for an account.
 *
 * @param {string} accountName The resource name of the account that owns the
 *     collection of ad clients.
 */
function listAdClients(accountName) {
  let pageToken;
  do {
    const response = AdSense.Accounts.Adclients.list(accountName, {
      pageToken: pageToken,
    });
    if (!response.adClients) {
      console.log("No ad clients found for this account.");
      return;
    }
    for (const adClient of response.adClients) {
      console.log(
        'Found ad client for product "%s" with resource name "%s".',
        adClient.productCode,
        adClient.name,
      );
      console.log(
        "Reporting dimension ID: %s",
        adClient.reportingDimensionId ?? "None",
      );
    }
    pageToken = response.nextPageToken;
  } while (pageToken);
}

عرض الوحدات الإعلانية

تعرض هذه العيّنة جميع الوحدات الإعلانية لعميل إعلاني معيّن. حدِّد عميل الإعلان كاسم مورد، مثل accounts/pub-12345/adclients/ca-pub-12345. يمكنك الحصول على اسم مصدر عميل الإعلان باستخدام نموذج الرمز عرض قائمة بعملاء الإعلانات.

advanced/adsense.gs

عرض على GitHub

/**
 * Lists ad units.
 * @param {string} adClientName The resource name of the ad client that owns the collection
 *     of ad units.
 */
function listAdUnits(adClientName) {
  let pageToken;
  do {
    const response = AdSense.Accounts.Adclients.Adunits.list(adClientName, {
      pageSize: 50,
      pageToken: pageToken,
    });
    if (!response.adUnits) {
      console.log("No ad units found for this ad client.");
      return;
    }
    for (const adUnit of response.adUnits) {
      console.log(
        'Found ad unit with resource name "%s" and display name "%s".',
        adUnit.name,
        adUnit.displayName,
      );
    }

    pageToken = response.nextPageToken;
  } while (pageToken);
}

إنشاء تقرير

ينشئ هذا النموذج تقريرًا عن حسابك على AdSense ويعرض النتائج في جدول بيانات.

advanced/adsense.gs

عرض على GitHub

/**
 * Generates a spreadsheet report for a specific ad client in an account.
 * @param {string} accountName The resource name of the account.
 * @param {string} adClientReportingDimensionId The reporting dimension ID
 *     of the ad client.
 */
function generateReport(accountName, adClientReportingDimensionId) {
  // Prepare report.
  const today = new Date();
  const oneWeekAgo = new Date(today.getTime() - 7 * 24 * 60 * 60 * 1000);

  const report = AdSense.Accounts.Reports.generate(accountName, {
    // Specify the desired ad client using a filter.
    filters: [
      `AD_CLIENT_ID==${escapeFilterParameter(adClientReportingDimensionId)}`,
    ],
    metrics: [
      "PAGE_VIEWS",
      "AD_REQUESTS",
      "AD_REQUESTS_COVERAGE",
      "CLICKS",
      "AD_REQUESTS_CTR",
      "COST_PER_CLICK",
      "AD_REQUESTS_RPM",
      "ESTIMATED_EARNINGS",
    ],
    dimensions: ["DATE"],
    ...dateToJson("startDate", oneWeekAgo),
    ...dateToJson("endDate", today),
    // Sort by ascending date.
    orderBy: ["+DATE"],
  });

  if (!report.rows) {
    console.log("No rows returned.");
    return;
  }
  const spreadsheet = SpreadsheetApp.create("AdSense Report");
  const sheet = spreadsheet.getActiveSheet();

  // Append the headers.
  sheet.appendRow(report.headers.map((header) => header.name));

  // Append the results.
  sheet
    .getRange(2, 1, report.rows.length, report.headers.length)
    .setValues(report.rows.map((row) => row.cells.map((cell) => cell.value)));

  console.log("Report spreadsheet created: %s", spreadsheet.getUrl());
}

/**
 * Escape special characters for a parameter being used in a filter.
 * @param {string} parameter The parameter to be escaped.
 * @return {string} The escaped parameter.
 */
function escapeFilterParameter(parameter) {
  return parameter.replace("\\", "\\\\").replace(",", "\\,");
}

/**
 * Returns the JSON representation of a Date object (as a google.type.Date).
 *
 * @param {string} paramName the name of the date parameter
 * @param {Date} value the date
 * @return {object} formatted date
 */
function dateToJson(paramName, value) {
  return {
    [`${paramName}.year`]: value.getFullYear(),
    [`${paramName}.month`]: value.getMonth() + 1,
    [`${paramName}.day`]: value.getDate(),
  };
}