مواد عرض المواقع الجغرافية

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

إنشاء مجموعة مواد عرض لمزامنة المواقع الجغرافية وربطها بالعميل

  1. أنشئ مجموعة مواد عرض مزامنة المواقع الجغرافية.
  2. ربطها بأحد العملاء باستخدام CustomerAssetSetService

إنشاء مجموعة مواد عرض لمزامنة المواقع الجغرافية

  1. أنشِئ AssetSet جديدًا.
    1. اضبط type على LOCATION_SYNC.
    2. اضبط location_set على LocationSet جديد.

  2. في تجربة LocationSet الجديدة،

    1. اضبط location_ownership_type استنادًا إلى حالة الاستخدام:
      • اضبط القيمة على BUSINESS_OWNER إذا كنت تملك الموقع الجغرافي للنشاط التجاري.
      • اضبط القيمة على AFFILIATE إذا كنت لا تملك الموقع الجغرافي للنشاط التجاري، ولكنك تبيع منتجاتك فيه.

    2. اضبط حقل source oneof استنادًا إلى حالة الاستخدام:

      • اضبط business_profile_location_set إذا كنت تريد المزامنة مع مواقعك الجغرافية في حسابك على الملف التجاري على Google.

        عند إنشاء BusinessProfileLocationSet لربط حساب "إعلانات Google" بحساب على "الملف التجاري على Google"، عليك تقديم رمز الدخول OAuth 2.0 في الحقل http_authorization_token. ويُعدّ هذا الرمز المميّز دليلاً على أنّك تسمح لخدمة "إعلانات Google" بالوصول إلى بيانات الموقع الجغرافي من "الملف التجاري على Google" المحدّد.

        يجب أن يستوفي الرمز المميّز المتطلبات التالية:

        • يجب إنشاء هذا الرمز لحساب Google (مستخدم أو حساب خدمة) الذي تم تقديم عنوان بريده الإلكتروني في الحقل email_address من BusinessProfileLocationSet.
        • يجب أن يملك هذا الحساب أذونات كافية لقراءة عناوين المؤسسات ضمن "الملف التجاري على Google".
        • يجب الحصول على رمز OAuth 2.0 المميز باستخدام النطاق https://www.googleapis.com/auth/business.manage.

        للحصول على تعليمات مفصّلة حول كيفية إنشاء رمز مميّز للوصول إلى OAuth 2.0، يُرجى الرجوع إلى استخدام بروتوكول OAuth 2.0 للوصول إلى Google APIs.

      • اضبط chain_location_set إذا كنت تريد المزامنة مع المواقع الجغرافية التي تتضمّن أرقام تعريف سلاسل محدّدة.

      • اضبط maps_location_set إذا أردت إضافة المواقع الجغرافية يدويًا باستخدام معرّفات الأماكن.

بعد إكمال هذه الخطوات، تنشئ Google Ads API مواد عرض المواقع الجغرافية وتضيفها إلى مجموعة مواد عرض مزامنة المواقع الجغرافية التي تم إنشاؤها لك، على غرار ما يحدث عند إجراء ذلك يدويًا باستخدام AssetSetAssetService. وليس عليك معالجتها إلا إذا أردت إضافتها يدويًا إلى مجموعة مواد عرض ثابتة لمجموعات المواقع الجغرافية.

يمكن أن تتوفّر مجموعة واحدة فقط من مواد عرض مزامنة المواقع الجغرافية النشطة مع ضبط status على ENABLED لأحد العملاء. إذا كنت بحاجة إلى إنشاء نوع مختلف من مجموعة مواد عرض مزامنة المواقع الجغرافية، عليك إزالة المجموعة الحالية أولاً.

إرفاق مجموعة مواد عرض مزامنة الموقع الجغرافي بعميل

استخدِم CustomerAssetSetService.MutateCustomerAssetSets لربط مجموعة مواد عرض مزامنة الموقع الجغرافي التي تم إعدادها في القسم السابق بعميلك.

(اختياري) إنشاء مجموعة مواد عرض لمجموعات المواقع الجغرافية وإرفاقها بحملة أو مجموعة إعلانية

لا تكون مجموعة مواد عرض مجموعات المواقع الجغرافية ضرورية إلا إذا كنت بحاجة إلى اختيار مجموعة فرعية من مواد عرض المواقع الجغرافية. يرجع ذلك إلى أنّ الحملات والمجموعات الإعلانية تكتسب مواد عرض المواقع الجغرافية من مستوى العميل.

تحتوي مجموعات مواد عرض مجموعات المواقع الجغرافية على مجموعة فرعية من مواد عرض المواقع الجغرافية لمجموعة مواد عرض مزامنة المواقع الجغرافية. يمكنك إنشاء مجموعة مواد عرض لمجموعات المواقع الجغرافية بشكل ديناميكي من خلال الاستفادة من بعض ميزات "الملف التجاري على Google" (مثل الفلترة حسب التصنيفات) أو أرقام تعريف السلاسل والمواقع الجغرافية للسلاسل. بدلاً من ذلك، يمكنك إنشاء مجموعة مواد عرض لمجموعات المواقع الجغرافية بشكل ثابت.

  1. إنشاء مجموعة مواد عرض لمجموعة مواقع جغرافية يمكن أن تكون مجموعة مواد عرض مجموعات المواقع الجغرافية ديناميكية أو ثابتة.
  2. اربط مجموعة مواد العرض بحملة أو مجموعة إعلانية، حسب احتياجاتك.
  3. (اختياري) أضِف مواد العرض التي تم إنشاؤها سابقًا إلى مجموعة مواد العرض الجديدة الخاصة بمجموعة المواقع الجغرافية الثابتة.

بالنسبة إلى عميل معيّن، يمكنك إنشاء مجموعات مواد عرض متعددة لمجموعات المواقع الجغرافية الديناميكية أو الثابتة.

إنشاء مجموعة مواد عرض لمجموعة مواقع جغرافية

أنشئ AssetSet جديدًا واضبط location_group_parent_asset_set_id على معرّف مجموعة مواد عرض مزامنة الموقع الجغرافي التي تم إنشاؤها سابقًا.

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

مجموعات مواد العرض الديناميكية

استنادًا إلى الحقل الذي ضبطته في LocationSet، اضبط الحقول استنادًا إلى القاعدة التالية:

في حال ضبط الحقل التالي بعد ذلك، اضبط type على واضبط هذا الحقل كحقل asset_set_source oneof
business_profile_location_set BUSINESS_PROFILE_DYNAMIC_LOCATION_GROUP business_profile_location_group
chain_location_set CHAIN_DYNAMIC_LOCATION_GROUP chain_location_group

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

مجموعات مواد العرض الثابتة

اضبط السمة type على STATIC_LOCATION_GROUP. يمكنك إنشاء مجموعات مواد عرض ثابتة لمجموعات المواقع الجغرافية لأي نوع من مجموعات مواد العرض التي تتم مزامنتها مع المواقع الجغرافية، بغض النظر عن الحقول (business_profile_location_set أو chain_location_set أو maps_location_set) التي تحدّدها في LocationSet.

بالنسبة إلى مجموعات مواد عرض المواقع الجغرافية الثابتة، عليك إضافة مواد عرض المواقع الجغرافية التي تم إنشاؤها يدويًا إلى مجموعات مواد عرض المواقع الجغرافية.

ربط مجموعة مواد العرض بحملة أو مجموعة إعلانية

استخدِم CampaignAssetSetService.MutateCampaignAssetSets لإرفاق مجموعة مواد عرض مجموعات المواقع الجغرافية بحملتك.

بدلاً من ذلك، استخدِم AdGroupAssetSetService.MutateAdGroupAssetSets إذا أردت إرفاق مجموعة مواد عرض مجموعات المواقع الجغرافية بمجموعة إعلانية بدلاً من ذلك.

(اختياري) أضِف مواد عرض المواقع الجغرافية إلى مجموعة مواد عرض المواقع الجغرافية الثابتة.

هذه الخطوة مطلوبة فقط إذا أنشأت مجموعة مواد عرض ثابتة لمجموعات المواقع الجغرافية سابقًا.

  1. استخدِم تقرير asset_set_asset لاسترجاع أسماء الموارد لمواد العرض التي تم إنشاؤها تلقائيًا لمجموعة مواد عرض مزامنة المواقع الجغرافية التي تم إنشاؤها سابقًا. استخدِم الفلترة لاسترداد مواد العرض التي تريدها فقط.
  2. أضِفها إلى مجموعة مواد عرض مجموعات المواقع الجغرافية الثابتة باستخدام AssetSetAssetService.MutateAssetSetAssets.

إدارة معرّفات المواقع الجغرافية في "الملف التجاري على Google"

عند استخدام business_profile_location_set والفلترة حسب listing_id_filters التي يتم استردادها من موقع "الملف التجاري" الإلكتروني أو واجهة برمجة التطبيقات، قد يكون من الضروري تحويل هذه القيم الرقمية من النوع uint64 إلى int64. إذا كان الرمز البرمجي يعرض خطأ أثناء التشغيل بأنّ رقم تعريف الموقع الجغرافي الخاص بملفك التجاري خارج النطاق عند إضافته إلى الحقل المتكرّر listing_id_filters[]، من المحتمل أنّك بحاجة إلى تحويله باستخدام أيّ من الأمثلة التالية:

جافا

/**
 * Converts the business profile location ID to the format expected by the
 * DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
 * The business profile location ID is an unsigned 64-bit integer, while the
 * listing_id_filters[] field expects signed 64-bit integers. This means that
 * for business profile location IDs that are out of range, we must perform the
 * two's complement to convert it into a signed int.
 *
 * @param businessProfileLocationId The ID of a Business Profile location ID.
 * @return a Business Profile location ID as a signed 64-bit integer (long).
 */
public static long convertBusinessProfileLocationId(String businessProfileLocationId) {
    return Long.parseUnsignedLong(businessProfileLocationId);
}

#C

/// <summary>
/// Converts the business profile location ID to the format expected by the
/// DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
/// The business profile location ID is an unsigned 64-bit integer, while the
/// listing_id_filters[] field expects signed 64-bit integers. This means that
/// for business profile location IDs that are out of range, we must perform the
/// two's complement to convert it into a signed int.
/// </summary>
/// <param name="businessProfileLocationId">The ID of a Business Profile location.</param>
/// <returns>The converted business location ID in signed 64 bit.</returns>
public long ConvertBusinessProfileLocationId(ulong businessProfileLocationId)
{
  return unchecked((long)businessProfileLocationId);
}

PHP

/**
* Converts a business profile location ID to a signed 64 bit integer.
*
* Converts the business profile location ID to the format expected by the
* DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
* The business profile location ID is an unsigned 64-bit integer, while the
* listing_id_filters[] field expects signed 64-bit integers. This means that
* for business profile location IDs that are out of range, we must perform the
* two's complement to convert it into a signed int.
*
* @param string $businessProfileLocationId the ID of a Business Profile location
* @return int the converted business location ID in signed 64 bit
*/
public static function convertBusinessProfileLocationId(string $businessProfileLocationId): int
{
    $unsignedMax = '18446744073709551615'; // 2^64 - 1
    $signedMax = '9223372036854775807'; // 2^63 - 1

    // Check if the business profile location ID is within 64 bit range.
    // If not, throw an error.
    if (bccomp($businessProfileLocationId, '0') < 0 || bccomp($businessProfileLocationId, $unsignedMax) > 0) {
        throw new InvalidArgumentException(
            'The given business profile location id is outside of the range for a 64 bit integer.'
        );
    }

    // Check if the business profile location ID is in signed 64 bit range.
    // If it's not, convert it to its two's complement.
    if (bccomp($businessProfileLocationId, $signedMax) > 0) {
        // Two's complement: ID - 2^64
        return (int) bcsub($businessProfileLocationId, '18446744073709551616');
    }

    return (int) $businessProfileLocationId;
}

Python

import ctypes

def convert_business_profile_location_id(business_profile_location_id):
    """Converts a business profile location ID to a signed 64 bit integer.

    Converts the business profile location ID to the format expected by the
    DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
    The business profile location ID is an unsigned 64-bit integer, while the
    listing_id_filters[] field expects signed 64-bit integers. This means that
    for business profile location IDs that are out of range, we must perform the
    two's complement to convert it into a signed int.

    Args:
        business_profile_location_id: the ID of a Business Profile location ID.

    Returns:
        a Business Profile location ID as a signed 64 bit integer.
    """
    # Check if the business profile location ID is within 64 bit range.
    # If not, throw an error.
    if business_profile_location_id < 0 or business_profile_location_id >= 2 ** 64:
        raise ValueError(
            "The given business profile location id is outside of the range for a 64 bit integer."
        )
    # Check if the business profile location ID is in signed 64 bit range.
    # If it's not, convert it to its two's complement.
    elif business_profile_location_id >= 2 ** 63:
        return ctypes.c_int64(business_profile_location_id).value
    else:
        return business_profile_location_id

Ruby

# Converts the business profile location ID to the format expected by the
# DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
# The business profile location ID is an unsigned 64-bit integer, while the
# listing_id_filters[] field expects signed 64-bit integers. This means that
# for business profile location IDs that are out of range, we must perform the
# two's complement to convert it into a signed int.
# Since Ruby supports arbitrary precision numbers, we have to calculate it
# manually.
LONG_MAX = 2 ** 63
ULONG_MAX = LONG_MAX * 2
def convert_business_profile_location_id(business_profile_location_id)
  # Check if the business profile location ID is within 64 bit range.
  # If not, throw an error.
  if business_profile_location_id < 0 || business_profile_location_id >= 2 ** 64
    raise "The given business profile location id is outside of the range for a 64 bit integer."
  # Check if the business profile location ID is in signed 64 bit range.
  # If it's not, convert it to its two's complement.
  elsif business_profile_location_id >= 2**63
    -1 * (ULONG_MAX - business_profile_location_id)
  else
    business_profile_location_id
  end
end

Perl

use bigint;

# Converts the business profile location ID to the format expected by the
# DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
# The business profile location ID is an unsigned 64-bit integer, while the
# listing_id_filters[] field expects signed 64-bit integers. This means that
# for business profile location IDs that are out of range, we must perform the
# two's complement to convert it into a signed int.
sub convert_business_profile_location_id {
  my ($business_profile_location_id) = @_;

  # Check if the business profile location ID is within 64 bit range.
  # If not, throw an error.
  if ($business_profile_location_id < 0 || $business_profile_location_id >= 2**64) {
    die "The given business profile location id is outside of the range for a 64 bit integer";
  # Check if the business profile location ID is in signed 64 bit range.
  # If it's not, convert it to its two's complement.
  } elsif ($business_profile_location_id >= 2**63) {
    return -1 * (2**64 - $business_profile_location_id);
  } else {
    return $business_profile_location_id;
  }
}
السابق
الإنشاء والاستخدام
التالي
مواد العرض التلقائية