راهنمای مخاطبان سفارشی

مخاطبان سفارشی (که شامل مخاطبان با قصد و نیت سفارشی قدیمی و مخاطبان با تمایل سفارشی می‌شود) به تبلیغ‌کنندگان اجازه می‌دهد تا با وارد کردن کلمات کلیدی مرتبط، URLها و برنامه‌های مرتبط با محصولات یا خدمات خود، به مخاطبان هدف ایده‌آل برسند. گوگل ادز به‌طور خودکار مناسب‌ترین هدف‌گیری مخاطبان را بر اساس نوع کمپین، استراتژی پیشنهاد قیمت و اهداف بهینه‌سازی تعیین می‌کند.

این راهنما، یک راهنمای جامع در مورد نحوه ایجاد و مدیریت مخاطبان سفارشی با استفاده از کلمات کلیدی و URLها با استفاده از API گوگل ادز ارائه می‌دهد.

۱. مخاطبان سفارشی را درک کنید

در API گوگل ادز، مفاهیم قدیمی مانند Custom Intent و Custom Affinity در یک منبع جامع واحد به نام Custom Audiences (مخاطبان سفارشی) ادغام شده‌اند.

وقتی مخاطب سفارشی را هدف قرار می‌دهید، گوگل ادز تبلیغات را به کاربرانی با این علایق یا قصد خرید در کمپین‌های Display، Demand Gen، Gmail، Video و Performance Max نشان می‌دهد:

  • اعضای کلمات کلیدی: به کاربرانی که عبارات خاصی را در گوگل جستجو می‌کنند یا کاربرانی که علایق مرتبط با آن کلمات کلیدی دارند، دسترسی پیدا کنید.
  • اعضای URL: به کاربرانی دسترسی پیدا کنید که وب‌سایت‌های مشابه URLهای مشخص‌شده را مرور می‌کنند.
  • اعضای برنامه: به کاربرانی که از برنامه‌های کاربردی تلفن همراه خاص استفاده می‌کنند، دسترسی پیدا کنید.

۲. پیش‌نیازها

قبل از ایجاد مخاطبان سفارشی، مطمئن شوید که موارد زیر را دارید:

  1. تکمیل فرآیند راه‌اندازی اولیه API: برای دستورالعمل‌های مربوط به دریافت توکن توسعه‌دهنده، راه‌اندازی Google Cloud و پیکربندی OAuth 2.0 به راهنمای راه‌اندازی اولیه مراجعه کنید.
  2. شناسه مشتری هدف: شناسه حساب کاربری مشتری گوگل ادز ۱۰ رقمی که مخاطب سفارشی در آن ایجاد خواهد شد.
  3. کتابخانه کلاینت نصب‌شده: کتابخانه کلاینت رسمی گوگل ادز (مثلاً google-ads برای پایتون).

۳. منابع و معماری API اصلی

مدیریت مخاطبان سفارشی شامل چندین موجودیت مجزای Protocol Buffer (Protobuf) در API گوگل ادز است:

CustomAudienceService

سرویس gRPC مسئول مدیریت مخاطبان سفارشی است. متدهای کلیدی شامل MutateCustomAudiences است که لیستی از عملیات را برای ایجاد، به‌روزرسانی یا حذف مخاطبان دریافت می‌کند.

CustomAudience

منبع اصلی که مخاطب را نشان می‌دهد ( CustomAudience ). فیلدهای کلیدی:

  • name : یک نام توصیفی و منحصر به فرد برای مخاطب سفارشی.
  • description : متن اختیاری که مخاطب هدف را توصیف می‌کند.
  • status : برای فعال و قابل استفاده کردن مخاطبان، آن را روی ENABLED تنظیم کنید.
  • type : نوع مخاطب سفارشی ( AUTO یا SEARCH ).
  • members : فهرستی از اشیاء CustomAudienceMember که سیگنال‌های هدف را تعریف می‌کنند.

CustomAudienceMember

یک سیگنال هدف‌گیری فردی در بین مخاطبان ( CustomAudienceMember ).

  • member_type : نوع شمارشی که نوع سیگنال ( KEYWORD ، URL ، APP ) را مشخص می‌کند.
  • keyword / url / app : مقدار رشته‌ای مربوط به نوع عضو.

۴. اجرای گام به گام

مرحله ۱: مقداردهی اولیه کلاینت

با استفاده از فایل google-ads.yaml پیکربندی‌شده، GoogleAdsClient را نمونه‌سازی کنید.

from google.ads.googleads.client import GoogleAdsClient

# Initialize the Google Ads client library
client = GoogleAdsClient.load_from_storage()
custom_audience_service = client.get_service("CustomAudienceService")

مرحله ۲: مخاطبان سفارشی را بسازید

یک نمونه CustomAudience جدید ایجاد کنید و فراداده‌های آن (نام، توضیحات، نوع، وضعیت) را پیکربندی کنید.

# Construct the CustomAudience resource
custom_audience = client.get_type("CustomAudience")
custom_audience.name = "Target Audience Name"
custom_audience.description = "Description of the target audience."
custom_audience.type_ = client.enums.CustomAudienceTypeEnum.AUTO
custom_audience.status = client.enums.CustomAudienceStatusEnum.ENABLED

مرحله ۳: اعضای کلمات کلیدی را جمع کنید

اشیاء CustomAudienceMember نمونه‌سازی کنید، member_type روی CustomAudienceMemberTypeEnum.KEYWORD تنظیم کنید و فیلد رشته keyword را با عبارات هدف خود پر کنید.

# Create and append a keyword member
keyword_member = client.get_type("CustomAudienceMember")
keyword_member.member_type = client.enums.CustomAudienceMemberTypeEnum.KEYWORD
keyword_member.keyword = "marathon training"
custom_audience.members.append(keyword_member)

مرحله ۴: پر کردن اعضای URL

اشیاء CustomAudienceMember نمونه‌سازی کنید، member_type روی CustomAudienceMemberTypeEnum.URL تنظیم کنید و فیلد رشته url را با وب‌سایت‌های رقیب یا صنعت پر کنید.

# Create and append a URL member
url_member = client.get_type("CustomAudienceMember")
url_member.member_type = client.enums.CustomAudienceMemberTypeEnum.URL
url_member.url = "https://www.runnersworld.com"
custom_audience.members.append(url_member)

مرحله ۵: اجرای جهش

CustomAudience در یک CustomAudienceOperation قرار دهید، آن را روی فیلد create تنظیم کنید و CustomAudienceService.mutate_custom_audiences() را فراخوانی کنید.

# Wrap in an operation and execute the mutation request
operation = client.get_type("CustomAudienceOperation")
operation.create = custom_audience

response = custom_audience_service.mutate_custom_audiences(
    customer_id="1234567890", operations=[operation]
)
print(f"Created custom audience: {response.results[0].resource_name}")

۵. مثال کامل کد پایتون

در زیر یک اسکریپت پایتون کاملاً کاربردی وجود دارد که نحوه ایجاد یک مخاطب سفارشی با هر دو کلمه کلیدی و اعضای URL را نشان می‌دهد.

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def create_custom_intent_audience(client: GoogleAdsClient, customer_id: str):
    """Creates a custom audience using keywords and URLs."""
    
    # 1. Get the CustomAudienceService
    custom_audience_service = client.get_service("CustomAudienceService")
    
    # 2. Create the CustomAudience resource
    custom_audience = client.get_type("CustomAudience")
    custom_audience.name = "Running Enthusiasts & Gear Shoppers"
    custom_audience.description = "Targeting users actively researching running shoes and visiting marathon websites."
    
    # Use AUTO for standard custom audiences (combines intent and affinity signals)
    custom_audience.type_ = client.enums.CustomAudienceTypeEnum.AUTO
    custom_audience.status = client.enums.CustomAudienceStatusEnum.ENABLED

    # 3. Add Keyword Members (Search Terms / Purchase Intent Keywords)
    keywords = [
        "best marathon running shoes",
        "carbon plate running shoes",
        "marathon training plan",
        "trail running gear"
    ]
    
    for kw in keywords:
        member = client.get_type("CustomAudienceMember")
        member.member_type = client.enums.CustomAudienceMemberTypeEnum.KEYWORD
        member.keyword = kw
        custom_audience.members.append(member)

    # 4. Add URL Members (Relevant websites/competitors)
    urls = [
        "https://www.runnersworld.com",
        "https://www.marathonrunning.com",
        "https://www.trailrunnermag.com"
    ]
    
    for url in urls:
        member = client.get_type("CustomAudienceMember")
        member.member_type = client.enums.CustomAudienceMemberTypeEnum.URL
        member.url = url
        custom_audience.members.append(member)

    # 5. Create the Operation
    operation = client.get_type("CustomAudienceOperation")
    operation.create = custom_audience

    # 6. Issue the Mutate Request
    try:
        response = custom_audience_service.mutate_custom_audiences(
            customer_id=customer_id, operations=[operation]
        )
        created_resource_name = response.results[0].resource_name
        print(f"Successfully created Custom Audience with resource name: '{created_resource_name}'")
    except GoogleAdsException as ex:
        print(f"Request failed with status {ex.error.code().name} and includes the following errors:")
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

if __name__ == "__main__":
    # Ensure the client is configured correctly (loads from google-ads.yaml)
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your actual Google Ads Customer ID (without hyphens)
        target_customer_id = "1234567890"
        create_custom_intent_audience(googleads_client, target_customer_id)
    except GoogleAdsException as ex:
        print(f"Failed to initialize client or execute request: {ex}")
        sys.exit(1)

۶. مخاطبان سفارشی را در کمپین‌ها اعمال کنید

پس از ایجاد یک مخاطب سفارشی، در کتابخانه مخاطبان حساب شما وجود دارد اما تا زمانی که به یک گروه تبلیغاتی یا کمپین متصل نشود، به طور فعال کاربران را هدف قرار نمی‌دهد.

AdGroupCriterion چیست؟

در معماری API گوگل ادز، قوانین هدف‌گذاری (مانند کلمات کلیدی، مخاطبان، جایگاه‌ها و اطلاعات جمعیتی) مستقیماً در شیء گروه تبلیغاتی پیکربندی نمی‌شوند. در عوض، گوگل ادز تمام روش‌های هدف‌گذاری را تحت یک نهاد مستقل به نام AdGroupCriterion یکپارچه می‌کند.

یک AdGroupCriterion به عنوان یک ظرف جهانی عمل می‌کند. شما مشخص می‌کنید که این AdGroupCriterion به کدام گروه تبلیغاتی اعمال می‌شود و سپس دقیقاً یکی از فیلدهای هدف‌گیری خاص آن (مثلاً keyword ، custom_audience یا placement ) را پر می‌کنید. با ایجاد یک AdGroupCriterion و پیکربندی فیلد custom_audience آن، به Google Ads دستور می‌دهید که نمایش تبلیغات را برای آن گروه تبلیغاتی بر اساس اعضای مخاطب سفارشی شما محدود یا مشاهده کند.

تجزیه گام به گام (ایجاد دو مرحله‌ای صریح)

برای تمایز واضح بین پیکربندی هدف‌گیری و کانتینر درخواست API، از الگوی ایجاد دو مرحله‌ای صریح استفاده می‌کنیم:

  1. نمونه‌سازی یک منبع AdGroupCriterion : یک شیء AdGroupCriterion مستقل ایجاد کنید. این منبع نشان دهنده رابطه هدف‌گیری است.
  2. تنظیم ad_group هدف: نام منبع قالب‌بندی‌شده گروه تبلیغاتی خود (مثلاً customers/{customer_id}/adGroups/{ad_group_id} ) را به فیلد ad_group معیار اختصاص دهید.
  3. فیلد custom_audience را پر کنید: نام resource_name مخاطب سفارشی (Custom Audience) که قبلاً ایجاد کرده‌اید را به ad_group_criterion.custom_audience.custom_audience اختصاص دهید.
  4. بسته‌بندی در یک AdGroupCriterionOperation : برای ارسال این معیار جدید به API، یک کانتینر AdGroupCriterionOperation نمونه‌سازی کنید و شیء معیار مستقل خود را به operation.create اختصاص دهید.
  5. ارسال با استفاده از AdGroupCriterionService : کانتینر عملیات را به mutate_ad_group_criteria() ارسال کنید تا عملیات ایجاد اجرا شود. 
import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def attach_custom_audience_to_ad_group(
    client: GoogleAdsClient, customer_id: str, ad_group_id: str, custom_audience_resource_name: str
):
    """Attaches a Custom Audience to an Ad Group using explicit two-step creation."""
    ad_group_criterion_service = client.get_service("AdGroupCriterionService")
    
    # Step 1: Instantiate the standalone AdGroupCriterion resource
    ad_group_criterion = client.get_type("AdGroupCriterion")
    
    # Step 2: Set the target Ad Group
    ad_group_criterion.ad_group = client.get_service("AdGroupService").ad_group_path(
        customer_id, ad_group_id
    )
    
    # Step 3: Set the custom audience targeting information
    ad_group_criterion.custom_audience.custom_audience = custom_audience_resource_name
    
    # Step 4: Package the resource into an AdGroupCriterionOperation
    operation = client.get_type("AdGroupCriterionOperation")
    operation.create = ad_group_criterion
    
    # Step 5: Issue the API Request
    try:
        response = ad_group_criterion_service.mutate_ad_group_criteria(
            customer_id=customer_id, operations=[operation]
        )
        print(
            "Successfully attached custom audience to Ad Group. "
            f"New criterion resource name: '{response.results[0].resource_name}'"
        )
    except GoogleAdsException as ex:
        print(f"Request failed with status {ex.error.code().name} and includes the following errors:")
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
        sys.exit(1)

۷. توصیه‌های سفارشی به مخاطبان

شما می‌توانید توصیه‌هایی از نوع CUSTOM_AUDIENCE_OPT_IN را بازیابی کنید که ایجاد مخاطب سفارشی را توصیه می‌کند. این امر به ویژه در صورتی مفید است که شما یک تبلیغ‌کننده شخص ثالث باشید که به کاربران خود امکان ایجاد و مدیریت بخش‌های مخاطب را می‌دهد. هنگامی که کاربران بر اساس توصیه برای ایجاد مخاطب سفارشی عمل می‌کنند، به بهبود امتیاز کلی بهینه‌سازی حساب کمک می‌کند.

برای اطلاعات بیشتر، به راهنمای امتیاز و توصیه‌های بهینه‌سازی مراجعه کنید.

۸. بهترین شیوه‌ها و محدودیت‌ها

کیفیت برتر از کمیت

روی کلمات کلیدی و URL های بسیار خاص و مرتبط تمرکز کنید. اضافه کردن صدها کلمه کلیدی عمومی، هدف را تضعیف کرده و کارایی کمپین را کاهش می‌دهد.

قوانین قالب‌بندی URL

  • URL ها باید آدرس های وب سایت معتبر باشند (مثلاً https://www.example.com ).
  • از زیرصفحات عمیق و بسیار خاص با ترافیک کم اجتناب کنید؛ URL های سطح دامنه یا سطح دسته بندی، دسترسی بهتری را فراهم می کنند.

محدودیت‌های اعضا

اگرچه مخاطبان سفارشی می‌توانند اعضای بی‌شماری را در خود جای دهند، اما فهرست‌ها را حول یک موضوع یا شخصیت منسجم برای هر مخاطب سفارشی متمرکز نگه دارید.

سیاست و حریم خصوصی

گوگل سیاست‌های سختگیرانه‌ای برای تبلیغات شخصی‌سازی‌شده اعمال می‌کند. از مخاطبان سفارشی برای هدف قرار دادن گروه‌های حساس مانند شرایط پزشکی، مشکلات مالی یا باورهای مذهبی استفاده نکنید.

۹. عملکرد لیست را بررسی کنید

قبل از اینکه بتوانید عملکرد را بررسی کنید، ابتدا باید مخاطب هدف سفارشی خود را به یک کمپین یا گروه تبلیغاتی متصل کنید، همانطور که در بخش «هدف قرار دادن مخاطب سفارشی» توضیح داده شده است.

برای جمع‌آوری داده‌های عملکرد برای بخش‌های مخاطبان خود، یک درخواست جستجو در ad_group_audience_view یا campaign_audience_view ارسال کنید. به عنوان مثال، می‌توانید به conversions یا cost_per_conversion نگاه کنید تا مشخص کنید که آیا هدف قرار دادن بخش مخاطبان واقعاً منجر به تبدیل‌های بیشتر می‌شود یا خیر، سپس اصلاح‌کننده‌های پیشنهاد قیمت خود را بر این اساس تنظیم کنید.

SELECT
  ad_group_criterion.criterion_id,
  metrics.conversions,
  metrics.cost_per_conversion
FROM ad_group_audience_view

۱۰. منابع و مراجع