الميزانيات المرنة - الحساب الإداري

رمز الأدوات

يعمل هذا النص البرمجي على توسيع الميزانيات المرونة ليتم تنفيذها في حسابات متعددة ضمن حساب إداري واحد. يمكن للميزانيات المرنة تعديل ميزانية حملتك ديناميكيًا يوميًا باستخدام مخطط مخصّص لتوزيع الميزانية.

يقرأ النص البرمجي جدول بيانات لكل حساب/حملة محدّدة والميزانية المقابلة (المرتبطة بتاريخ البدء وتاريخ الانتهاء)، ويبحث عن الحملة، ويحتسب ميزانية اليوم الحالي، ويحدّدها كميزانية يومية للحملة، ويسجّل النتيجة في جدول البيانات. ولن يتطرق إلى الحملات غير المحددة في جدول البيانات.

آلية العمل

يعمل النص البرمجي بالطريقة نفسها التي يعمل بها النص البرمجي للميزانية المرنة لحساب واحد. والوظيفة الإضافية الوحيدة هي أنها تدعم حسابات متعددة من خلال جدول البيانات المحدد.

يحدّد أول عمودَين الحملة التي سيتمّ احتساب الميزانية لها، ويحدّد الثلاثة التالية معلومات الميزانية، ويسجّل العمود الأخير نتيجة التنفيذ.

يجب أن يكون رقم تعريف الحساب حساب معلِن وليس حسابًا إداريًا.

يمكن أن يكون لديك ميزانيات متعددة للحساب نفسه/الحملة نفسها، ولكن احرص على توفُّر ميزانية نشطة واحدة فقط في كل مرة، وإلّا قد يحلّ حساب ميزانية جديد محلّ ميزانية قديمة

إذا لم يتم تحديد حساب أو حملة في جدول البيانات، لن يعيّن النص البرمجي ميزانية مرنة له.

اختبار استراتيجيات الميزانية

يتضمن البرنامج النصي اختبارًا برمجيًا لمحاكاة تأثيرات التشغيل لعدة أيام. يمنحك هذا فكرة أفضل عما يحدث عند جدولة النص البرمجي للتشغيل يوميًا على مدار فترة زمنية.

يحاكي هذا النص البرمجي تلقائيًا توزيعًا متساويًا للميزانية بقيمة 500 دولار أمريكي (أو ما يعادله بالعملة المحلية) يتم إنفاقه على مدار 10 أيام.

يمكنك تنفيذ رمز الاختبار من خلال استدعاء testBudgetStrategy بدلاً من setNewBudget في الطريقة الرئيسية:

function main() {
  testBudgetStrategy(calculateBudgetEvenly, 10, 500);
  //  setNewBudget(calculateBudgetWeighted);
}

تم تعليق استدعاء الدالة setNewBudget، ما يشير إلى أنّ النص البرمجي يشغِّل رمز اختبار. إليك مخرج المثال:

Day 1.0 of 10.0, new budget 50.0, cost so far 0.0
Day 2.0 of 10.0, new budget 50.0, cost so far 50.0
Day 3.0 of 10.0, new budget 50.0, cost so far 100.0
Day 4.0 of 10.0, new budget 50.0, cost so far 150.0
Day 5.0 of 10.0, new budget 50.0, cost so far 200.0
Day 6.0 of 10.0, new budget 50.0, cost so far 250.0
Day 7.0 of 10.0, new budget 50.0, cost so far 300.0
Day 8.0 of 10.0, new budget 50.0, cost so far 350.0
Day 9.0 of 10.0, new budget 50.0, cost so far 400.0
Day 10.0 of 10.0, new budget 50.0, cost so far 450.0
Day 11.0 of 10.0, new budget 0.0, cost so far 500.0

يتم حساب ميزانية جديدة كل يوم للتأكد من إنفاق الميزانية بشكل متساوٍ كل يوم. بعد تجاوز الحصة الأولية للميزانية، يتم ضبط الميزانية على صفر لوقف الإنفاق.

يمكنك تغيير استراتيجية الميزانية المستخدَمة عن طريق تغيير الدالة المستخدَمة أو عن طريق تعديل الدالة نفسها. يتضمّن النص البرمجي استراتيجيتَين معدّتين مسبقًا: calculateBudgetEvenly وcalculateBudgetWeighted. وقد اختبر المثال السابق الاستراتيجيتَين السابقتَين. عدِّل السطر testBudgetStrategy لاستخدام اللاحقة:

testBudgetStrategy(calculateBudgetWeighted, 10, 500);

انقر على Preview (معاينة) وتحقّق من مخرجات المسجِّل. لاحظ أن استراتيجية الميزانية هذه تخصص ميزانية أقل في وقت مبكر من الفترة وتزيدها في الأيام القليلة التالية.

يمكنك استخدام طريقة الاختبار هذه لمحاكاة التغييرات على دوال حساب الميزانية وتجربة نهجك الخاص لتوزيع الميزانية.

تخصيص الميزانية

لنلقِ نظرة عن كثب على استراتيجية الميزانية "calculateBudgetWeighted":

// One calculation logic that distributes remaining budget in a weighted manner
function calculateBudgetWeighted(costSoFar, totalBudget, daysSoFar, totalDays) {
  const daysRemaining = totalDays - daysSoFar;
  const budgetRemaining = totalBudget - costSoFar;
  if (daysRemaining <= 0) {
    return budgetRemaining;
  } else {
    return budgetRemaining / (2 * daysRemaining - 1);
  }
}

تستخدم هذه الدالة الوسيطات التالية:

  • costSoFar: ما هي تكلفة هذه الحملة المتراكمة من startDate حتى اليوم.
  • totalBudget: المبلغ المطلوب إنفاقه من startDate إلى endDate
  • daysSoFar: عدد الأيام المنقضية من startDate إلى اليوم
  • totalDays: إجمالي عدد الأيام بين startDate وendDate.

يمكنك كتابة الدالة الخاصة بك طالما أنها تستغرق هذه الوسيطات. باستخدام هذه القيم، يمكنك مقارنة مقدار الأموال التي أنفقتها حتى الآن بالمبلغ الذي يجب إنفاقه بشكل عام وتحديد مكانك حاليًا ضمن الجدول الزمني للميزانية بأكملها.

على وجه التحديد، تحدِّد استراتيجية الميزانية هذه مقدار الميزانية المتبقية (totalBudget - costSoFar) وتقسمه على ضِعف عدد الأيام المتبقية. وهي تضع توزيع الميزانية نحو نهاية الحملة. وعند استخدام التكلفة منذ startDate، تأخذ في الاعتبار أيضًا "الأيام البطيئة" التي لا يتم فيها إنفاق الميزانية الكاملة التي حدّدتها.

وضع الميزانية في مرحلة الإنتاج

عندما تصبح راضيًا عن استراتيجية الميزانية، ستحتاج إلى إجراء بعض التغييرات قبل أن تتمكّن من جدولة هذا النص البرمجي للتشغيل يوميًا.

أولاً، عليك تعديل جدول البيانات لتحديد الحساب والحملة والميزانية وتاريخ البدء وتاريخ الانتهاء - صف واحد لكل ميزانية حملة.

  • رقم تعريف الحساب: رقم تعريف الحساب (بالتنسيق xxx-xxx-xxxx) للحملة لتطبيق استراتيجية الميزانية عليها.
  • اسم الحملة: اسم الحملة التي تريد تطبيق استراتيجية الميزانية عليها.
  • تاريخ البدء: تاريخ بدء استراتيجية الميزانية. يمكن أن يكون هذا هو التاريخ الحالي أو يوم في الماضي.
  • تاريخ الانتهاء: آخر يوم تريد عرض الإعلانات فيه باستخدام هذه الميزانية.
  • إجمالي الميزانية: إجمالي المبلغ الذي تحاول إنفاقه. تكون هذه القيمة بعملة الحساب ويمكن أن يتم تجاوزها بناءً على الوقت الذي تمت جدولة تشغيل النص البرمجي فيه.

بعد ذلك، أوقِف الاختبار وفعِّل المنطق لتغيير الميزانية فعليًا:

function main() {
  //  testBudgetStrategy(calculateBudgetEvenly, 10, 500);
  setNewBudget(calculateBudgetWeighted);
}

ويتم تسجيل نتيجة كل حملة في عمود نتيجة التنفيذ.

الجدولة

يمكنك جدولة تشغيل هذا النص البرمجي يوميًا، في منتصف الليل أو بعده بقليل في المنطقة الزمنية المحلية، وذلك لكي يتم التحكّم قدر الإمكان في ميزانية اليوم التالي. ومع ذلك، يُرجى العلم أنّ عملية استرداد بيانات التقارير، مثل التكلفة، قد يتأخر عرضها لحوالي 3 ساعات، لذا قد تشير المَعلمة costSoFar إلى إجمالي البيانات الخاصة بالأمس لنص برمجي مُقرَّر تشغيله بعد منتصف الليل.

ضبط إعدادات الجهاز

  • انقر على الزر أدناه لإنشاء النص البرمجي في حسابك على "إعلانات Google".

    تثبيت نموذج النص البرمجي

  • انقر فوق الزر أدناه لإنشاء نسخة من جدول بيانات النموذج.

    نسخ جدول بيانات النموذج

  • تحديث spreadsheet_url في النص البرمجي.

  • حدِّد موعدًا لتنفيذ النص البرمجي يوميًا.

رمز مصدر

// Copyright 2015, Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

/**
 * @name MCC Flexible Budgets
 *
 * @overview The MCC Flexible Budgets script dynamically adjusts campaign budget
 *     daily for accounts under an MCC account with a custom budget distribution
 *     scheme. See
 *     https://developers.google.com/google-ads/scripts/docs/solutions/manager-flexible-budgets
 *     for more details.
 *
 * @author Google Ads Scripts Team [adwords-scripts@googlegroups.com]
 *
 * @version 2.1
 *
 * @changelog
 * - version 2.1
 *   - Split into info, config, and code.
 *  - version 2.0
 *   - Updated to use new Google Ads scripts features.
 * - version 1.0.4
 *   - Add support for video and shopping campaigns.
 * - version 1.0.3
 *   - Added validation for external spreadsheet setup.
 * - version 1.0.2
 *   - Fix a minor bug in variable naming.
 *   - Use setAmount on the budget instead of campaign.setBudget.
 * - version 1.0.1
 *   - Improvements to time zone handling.
 * - version 1.0
 *   - Released initial version.
 */
/**
 * Configuration to be used for the Flexible Budgets script.
 */
CONFIG = {
  // URL of the default spreadsheet template. This should be a copy of
  // https://docs.google.com/spreadsheets/d/17wocOgrLeRWF1Qi_BjEigCG0qVMebFHrbUS-Vk_kpLg/copy
  // Make sure the sheet is owned by or shared with same Google user executing the script
  'spreadsheet_url': 'YOUR_SPREADSHEET_URL',

  'advanced_options': {
    // Please fix the following variables if you need to reformat the
    // spreadsheet
    // column numbers of each config column. Column A in your spreadsheet has
    // column number of 1, B has number of 2, etc.
    'column': {
      'accountId': 2,
      'campaignName': 3,
      'startDate': 4,
      'endDate': 5,
      'totalBudget': 6,
      'results': 7
    },

    // Actual config (without header and margin) starts from this row
    'config_start_row': 5
  }
};

const SPREADSHEET_URL = CONFIG.spreadsheet_url;
const COLUMN = CONFIG.advanced_options.column;
const CONFIG_START_ROW = CONFIG.advanced_options.config_start_row;

function main() {
  // Uncomment the following function to test your budget strategy function
  // testBudgetStrategy(calculateBudgetEvenly, 10, 500);
  setNewBudget(calculateBudgetWeighted);
}

// Core logic for calculating and setting campaign daily budget
function setNewBudget(budgetFunc) {
  console.log(`Using spreadsheet - ${SPREADSHEET_URL}.`);
  const spreadsheet = validateAndGetSpreadsheet(SPREADSHEET_URL);
  spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());
  const sheet = spreadsheet.getSheets()[0];

  const endRow = sheet.getLastRow();

  const mccAccount = AdsApp.currentAccount();
  sheet.getRange(2, 6, 1, 2).setValue(mccAccount.getCustomerId());

  const today = new Date();

  for (let i = CONFIG_START_ROW; i <= endRow; i++) {
    console.log(`Processing row ${i}`);

    const accountId = sheet.getRange(i, COLUMN.accountId).getValue();
    const campaignName = sheet.getRange(i, COLUMN.campaignName).getValue();
    const startDate = new Date(sheet.getRange(i, COLUMN.startDate).getValue());
    const endDate = new Date(sheet.getRange(i, COLUMN.endDate).getValue());
    const totalBudget = sheet.getRange(i, COLUMN.totalBudget).getValue();
    const resultCell = sheet.getRange(i, COLUMN.results);

    const accountIter = AdsManagerApp.accounts().withIds([accountId]).get();
    if (!accountIter.hasNext()) {
      resultCell.setValue('Unknown account');
      continue;
    }
    const account = accountIter.next();
    AdsManagerApp.select(account);

    const campaign = getCampaign(campaignName);
    if (!campaign) {
      resultCell.setValue('Unknown campaign');
      continue;
    }

    if (today < startDate) {
      resultCell.setValue('Budget not started yet');
      continue;
    }
    if (today > endDate) {
      resultCell.setValue('Budget already finished');
      continue;
    }

    const costSoFar = campaign
                          .getStatsFor(
                              getDateStringInTimeZone('yyyyMMdd', startDate),
                              getDateStringInTimeZone('yyyyMMdd', endDate))
                          .getCost();
    const daysSoFar = datediff(startDate, today);
    const totalDays = datediff(startDate, endDate);
    const newBudget = budgetFunc(costSoFar, totalBudget, daysSoFar, totalDays);
    campaign.getBudget().setAmount(newBudget);
    console.log(
        `AccountId=${accountId}, CampaignName=${campaignName}, ` +
        `StartDate=${startDate}, EndDate=${endDate}, ` +
        `CostSoFar=${costSoFar}, DaysSoFar=${daysSoFar}, ` +
        `TotalDays=${totalDays}, NewBudget=${newBudget}'`);
    resultCell.setValue(`Set today's budget to ${newBudget}`);
  }

  // update "Last execution" timestamp
  sheet.getRange(1, 3).setValue(today);
  AdsManagerApp.select(mccAccount);
}

// One calculation logic that distributes remaining budget evenly
function calculateBudgetEvenly(costSoFar, totalBudget, daysSoFar, totalDays) {
  const daysRemaining = totalDays - daysSoFar;
  const budgetRemaining = totalBudget - costSoFar;
  if (daysRemaining <= 0) {
    return budgetRemaining;
  } else {
    return budgetRemaining / daysRemaining;
  }
}

// One calculation logic that distributes remaining budget in a weighted manner
function calculateBudgetWeighted(costSoFar, totalBudget, daysSoFar, totalDays) {
  const daysRemaining = totalDays - daysSoFar;
  const budgetRemaining = totalBudget - costSoFar;
  if (daysRemaining <= 0) {
    return budgetRemaining;
  } else {
    return budgetRemaining / (2 * daysRemaining - 1);
  }
}

// Test function to verify budget calculation logic
function testBudgetStrategy(budgetFunc, totalDays, totalBudget) {
  let daysSoFar = 0;
  let costSoFar = 0;
  while (daysSoFar <= totalDays + 2) {
    const newBudget = budgetFunc(costSoFar, totalBudget, daysSoFar, totalDays);
    console.log(
        `Day ${daysSoFar + 1} of ${totalDays}, ` +
        `new budget ${newBudget}, cost so far ${costSoFar}`);
    costSoFar += newBudget;
    daysSoFar += 1;
  }
}

// Return number of days between two dates, rounded up to nearest whole day.
function datediff(from, to) {
  const millisPerDay = 1000 * 60 * 60 * 24;
  return Math.ceil((to - from) / millisPerDay);
}

// Produces a formatted string representing a given date in a given time zone.
function getDateStringInTimeZone(format, date, timeZone) {
  date = date || new Date();
  timeZone = timeZone || AdsApp.currentAccount().getTimeZone();
  return Utilities.formatDate(date, timeZone, format);
}

/**
 * Finds a campaign by name, whether it is a regular, video, or shopping
 * campaign, by trying all in sequence until it finds one.
 *
 * @param {string} campaignName The campaign name to find.
 * @return {Object} The campaign found, or null if none was found.
 */
function getCampaign(campaignName) {
  const selectors =
      [AdsApp.campaigns(), AdsApp.videoCampaigns(), AdsApp.shoppingCampaigns()];
  for (const selector of selectors) {
    const campaignIter =
        selector.withCondition(`CampaignName = "${campaignName}"`).get();
    if (campaignIter.hasNext()) {
      return campaignIter.next();
    }
  }
  return null;
}

/**
 * Validates the provided spreadsheet URL to make sure that it's set up
 * properly. Throws a descriptive error message if validation fails.
 *
 * @param {string} spreadsheeturl The URL of the spreadsheet to open.
 * @return {Spreadsheet} The spreadsheet object itself, fetched from the URL.
 * @throws {Error} If the spreadsheet URL hasn't been set
 */
function validateAndGetSpreadsheet(spreadsheeturl) {
  if (spreadsheeturl == 'YOUR_SPREADSHEET_URL') {
    throw new Error(
        'Please specify a valid Spreadsheet URL. You can find' +
        ' a link to a template in the associated guide for this script.');
  }
  return SpreadsheetApp.openByUrl(spreadsheeturl);
}