গুগল অ্যাডস এপিআই-এর বিস্তারিত অনবোর্ডিং গাইড

এই নির্দেশিকায় গুগল অ্যাডস এপিআই-তে অনবোর্ডিং, প্রমাণীকরণ এবং আপনার প্রথম কল করার সম্পূর্ণ প্রক্রিয়াটি বিস্তারিতভাবে বর্ণনা করা হয়েছে।

১. পূর্বশর্তসমূহ এবং অ্যাকাউন্টের স্তরবিন্যাস

গুগল অ্যাডস এপিআই ব্যবহার করার আগে, আপনাকে অবশ্যই অ্যাকাউন্টের স্তরবিন্যাস বুঝতে হবে এবং সঠিক শীর্ষ-স্তরের অ্যাকাউন্ট কাঠামো তৈরি করতে হবে।

  • ম্যানেজার অ্যাকাউন্ট (MCC): একটি গুগল অ্যাডস ম্যানেজার অ্যাকাউন্ট (পূর্বে মাই ক্লায়েন্ট সেন্টার) হলো একটি প্রাথমিক অ্যাকাউন্ট যা একাধিক ক্লায়েন্ট অ্যাকাউন্ট দেখতে এবং পরিচালনা করতে ব্যবহৃত হয়। গুগল অ্যাডস এপিআই ডেভেলপার টোকেনের জন্য আবেদন করতে আপনার একটি ম্যানেজার অ্যাকাউন্ট থাকা আবশ্যক।
  • ক্লায়েন্ট অ্যাকাউন্ট: এটি হলো স্ট্যান্ডার্ড অ্যাকাউন্ট, যেখানে ক্যাম্পেইন, অ্যাড গ্রুপ ও বিজ্ঞাপন তৈরি করা হয় এবং বিলিং কনফিগার করা হয়।

করণীয়: আপনার যদি কোনো ম্যানেজার অ্যাকাউন্ট না থাকে, তাহলে Google Ads Manager Accounts থেকে একটি অ্যাকাউন্ট তৈরি করুন।

২. একটি ডেভেলপার টোকেন সংগ্রহ করুন।

ডেভেলপার টোকেনটি গুগল অ্যাডস এপিআই-এর কাছে আপনার অ্যাপ্লিকেশনকে অনন্যভাবে শনাক্ত করে এবং আপনার কল ভলিউম অ্যাক্সেস টিয়ার নিয়ন্ত্রণ করে।

আবেদন করার ধাপসমূহ

  1. আপনার গুগল অ্যাডস ম্যানেজার অ্যাকাউন্টে সাইন ইন করুন।
  2. টুলস এবং সেটিংস > সেটআপ > এপিআই সেন্টার (অথবা অ্যাডমিন > এপিআই সেন্টার )-এ যান।
  3. ডেভেলপার বিবরণী ফর্মটি পূরণ করুন এবং এপিআই পরিষেবার শর্তাবলীতে সম্মত হন।
  4. আপনার আবেদনপত্র জমা দিন।

অ্যাক্সেস স্তর

  • অনুমোদনের অপেক্ষায়: নতুন তৈরি করা টোকেনগুলো অবিলম্বে একটি "অনুমোদনের অপেক্ষায়" (Pending) স্ট্যাটাস পায়। আপনি একটি অপেক্ষাধীন টোকেন ব্যবহার করে অবিলম্বে টেস্ট অ্যাকাউন্টে সংযোগ করতে পারেন, কিন্তু এটি প্রোডাকশন অ্যাকাউন্টে কাজ করবে না।
  • বেসিক অ্যাক্সেস: অনুমোদিত হলে প্রতিদিন সর্বোচ্চ ১৫,০০০ এপিআই অপারেশন করার সুযোগ দেয়।
  • স্ট্যান্ডার্ড অ্যাক্সেস: প্রয়োজনীয় ন্যূনতম কার্যকারিতা (RMF) পূরণকারী অ্যাপ্লিকেশনগুলির জন্য সীমাহীন দৈনিক API অপারেশন।

৩. টেস্ট অ্যাকাউন্ট তৈরি করুন

প্রোডাকশন অ্যাকাউন্টে ডেভেলপমেন্ট ও টেস্টিং করার ফলে অনাকাঙ্ক্ষিত বিজ্ঞাপন খরচ এবং ক্যাম্পেইনে পরিবর্তনের ঝুঁকি থাকে। সমস্ত সক্রিয় ডেভেলপমেন্ট টেস্ট অ্যাকাউন্টে করার জন্য দৃঢ়ভাবে সুপারিশ করা হয়।

কীভাবে একটি টেস্ট ম্যানেজার অ্যাকাউন্ট তৈরি করবেন

  1. Google Ads Test Manager অ্যাকাউন্ট তৈরির পৃষ্ঠায় যান।
  2. এমন একটি Google অ্যাকাউন্ট দিয়ে সাইন ইন করুন যা আপনার প্রোডাকশন Google Ads Manager অ্যাকাউন্টের সাথে আগে থেকেই লিঙ্ক করা নেই ।
  3. একটি বর্ণনামূলক অ্যাকাউন্টের নাম লিখুন (যেমন, MyCompany Test MCC )।
  4. প্রাথমিক ব্যবহার হিসেবে ‘অন্যদের অ্যাকাউন্ট পরিচালনা’ নির্বাচন করুন।
  5. আপনার বিলিং দেশ, সময় অঞ্চল এবং মুদ্রা নির্বাচন করুন। সংরক্ষণ করুন এবং চালিয়ে যান-এ ক্লিক করুন।

কীভাবে একটি টেস্ট ক্লায়েন্ট অ্যাকাউন্ট তৈরি করবেন

আপনার টেস্ট ম্যানেজার অ্যাকাউন্ট তৈরি হয়ে গেলে, টেস্ট ক্যাম্পেইন চালানোর জন্য আপনাকে অবশ্যই অন্তত একটি চাইল্ড ক্লায়েন্ট অ্যাকাউন্ট তৈরি করতে হবে।

  1. আপনার নতুন তৈরি করা টেস্ট ম্যানেজার অ্যাকাউন্টে সাইন ইন করুন।
  2. বাম দিকের নেভিগেশন মেনু থেকে Accounts-এ ক্লিক করুন, তারপর Sub-account settings (অথবা Performance ) নির্বাচন করুন।
  3. নীল + (প্লাস) বোতামটি ক্লিক করুন এবং নতুন অ্যাকাউন্ট তৈরি করুন নির্বাচন করুন।
  4. গুগল অ্যাডস অ্যাকাউন্ট নির্বাচন করুন।
  5. একটি অ্যাকাউন্টের নাম লিখুন (যেমন, Test Client Account A )।
  6. একটি সময় অঞ্চল ও মুদ্রা নির্বাচন করুন, তারপর 'সংরক্ষণ করুন এবং চালিয়ে যান'- এ ক্লিক করুন।
  7. এই নতুন ক্লায়েন্ট অ্যাকাউন্টের ১০-সংখ্যার গ্রাহক আইডিটি (যেমন, হাইফেন ছাড়া 1234567890 ) লিখে রাখুন।

টেস্ট অ্যাকাউন্টের জন্য গুরুত্বপূর্ণ নিয়মাবলী

  • ডেভেলপার টোকেন ব্যবহার: আপনার টেস্ট ম্যানেজার অ্যাকাউন্ট থেকে ডেভেলপার টোকেনের জন্য আবেদন করবেন না । সর্বদা আপনার প্রোডাকশন ম্যানেজার অ্যাকাউন্ট থেকে অপেক্ষাধীন বা অনুমোদিত ডেভেলপার টোকেন ব্যবহার করুন।
  • বিলিং: টেস্ট অ্যাকাউন্টগুলোতে কোনো প্রকৃত বিজ্ঞাপন দেখানো হয় না, তাই আপনাকে আসল বিলিং তথ্য প্রবেশ করানোর প্রয়োজন নেই।

৪. গুগল ক্লাউড প্রজেক্ট সেটআপ

Google Ads API সক্রিয় করা একটি Google Cloud প্রজেক্ট ব্যবহার করে সমস্ত API অনুরোধ অবশ্যই প্রমাণীকৃত হতে হবে।

এপিআই সক্রিয় করার ধাপসমূহ

  1. গুগল ক্লাউড কনসোলে যান।
  2. একটি নতুন প্রকল্প তৈরি করুন অথবা একটি বিদ্যমান প্রকল্প নির্বাচন করুন।
  3. API ও পরিষেবা > লাইব্রেরি- তে যান।
  4. Google Ads API অনুসন্ধান করুন এবং সক্ষম করুন-এ ক্লিক করুন।

মূল্য নির্ধারণ এবং বিলিং নোট

  • কোনো এপিআই ফি নেই: গুগল ক্লাউড প্রজেক্ট তৈরি করা, গুগল অ্যাডস এপিআই সক্রিয় করা এবং OAuth 2.0 ক্রেডেনশিয়াল তৈরি করা ১০০% বিনামূল্যে । গুগল অ্যাডস এপিআই কল করা বা ব্যবহার করার জন্য গুগল নিজে কোনো ফি চার্জ করে না।
  • অন্যান্য ক্লাউড রিসোর্স: আপনি শুধুমাত্র তখনই গুগল ক্লাউড ফি প্রদান করবেন, যদি আপনি আপনার অ্যাপ্লিকেশন হোস্ট করতে বা আপনার বিজ্ঞাপনের ডেটা সংরক্ষণ করতে অন্যান্য বিলযোগ্য গুগল ক্লাউড পরিষেবা (যেমন Compute Engine, Cloud Run, বা BigQuery) তাদের ফ্রি টিয়ারের সীমা অতিক্রম করে সক্রিয়ভাবে ব্যবহার করেন।

৫. OAuth 2.0 প্রমাণীকরণ কনফিগারেশন

গুগল অ্যাডস এপিআই অনুরোধগুলির প্রমাণীকরণ এবং অনুমোদনের জন্য OAuth 2.0 ব্যবহার করে।

ডেস্কটপ বা ওয়েব অ্যাপ্লিকেশন প্রবাহের ধাপসমূহ

  1. আপনার গুগল ক্লাউড প্রজেক্টে, APIs & Services > OAuth consent screen- এ যান এবং কনসেন্ট স্ক্রিনটি কনফিগার করুন।
  2. এপিআই ও পরিষেবা > পরিচয়পত্র- এ যান।
  3. ক্রেডেনশিয়াল তৈরি করুন > OAuth ক্লায়েন্ট আইডি-তে ক্লিক করুন।
  4. অ্যাপ্লিকেশনটির ধরন নির্বাচন করুন (যেমন, ডেস্কটপ অ্যাপ অথবা ওয়েব অ্যাপ্লিকেশন )।
  5. তৈরি করুন- এ ক্লিক করুন। আপনার Client ID এবং Client Secret ডাউনলোড বা কপি করুন।

একটি রিফ্রেশ টোকেন তৈরি করুন

আপনার ক্লায়েন্ট আইডি এবং ক্লায়েন্ট সিক্রেট পেয়ে গেলে, আপনাকে অবশ্যই একটি রিফ্রেশ টোকেন তৈরি করতে হবে। আপনি গুগল ওঅথ ২.০ প্লেগ্রাউন্ড অথবা একটি ক্লায়েন্ট লাইব্রেরি স্ক্রিপ্ট ব্যবহার করে এটি করতে পারেন।

পদ্ধতি A: গুগল OAuth 2.0 প্লেগ্রাউন্ড (ওয়েব-ভিত্তিক) ব্যবহার করুন

  1. Google OAuth 2.0 প্লেগ্রাউন্ডে যান।
  2. উপরের ডান কোণায় থাকা গিয়ার আইকনে (OAuth 2.0 কনফিগারেশন) ক্লিক করুন।
  3. আপনার নিজের OAuth ক্রেডেনশিয়াল ব্যবহার করার জন্য বক্সটিতে টিক দিন।
  4. আপনার OAuth2 Client ID এবং Client Secret প্রবেশ করান, তারপর ক্লোজ-এ ক্লিক করুন।
  5. বামদিকের ধাপ ১ (এপিআই নির্বাচন ও অনুমোদন) -এ, 'আপনার নিজস্ব স্কোপ ইনপুট করুন' ফিল্ডে গুগল অ্যাডস এপিআই স্কোপটি ইনপুট করুন: https://www.googleapis.com/auth/adwords
  6. API অনুমোদন করুন-এ ক্লিক করুন। অনুরোধ করা হলে, সেই Google অ্যাকাউন্ট দিয়ে সাইন ইন করুন যেটির আপনার Google Ads Manager অ্যাকাউন্ট (বা টেস্ট অ্যাকাউন্ট)-এ অ্যাক্সেস আছে।
  7. সম্মতি স্ক্রিনে ' চালিয়ে যান'- এ ক্লিক করুন।
  8. ধাপ ২ (টোকেন বিনিময়ের জন্য অনুমোদন কোড) -এ, নীল রঙের ‘টোকেন বিনিময়ের জন্য অনুমোদন কোড’ বোতামটিতে ক্লিক করুন।
  9. আপনার Refresh token এবং Access token রেসপন্স প্যানেলে প্রদর্শিত হবে। Refresh token কপি করে সংরক্ষণ করুন।

পদ্ধতি B: ক্লায়েন্ট লাইব্রেরি স্ক্রিপ্ট ব্যবহার করুন (পাইথন উদাহরণ)

অফিসিয়াল পাইথন ক্লায়েন্ট লাইব্রেরি ক্রেডেনশিয়াল তৈরি করার জন্য একটি বিল্ট-ইন হেল্পার স্ক্রিপ্ট প্রদান করে। বিকল্পভাবে, আপনি নিম্নলিখিত স্বতন্ত্র পাইথন স্ক্রিপ্টটি চালাতে পারেন:

  1. প্রয়োজনীয় OAuth লাইব্রেরি ইনস্টল করুন: 
pip install google-auth-oauthlib
  1. generate_refresh_token.py নামে একটি স্ক্রিপ্ট তৈরি করুন এবং সেটি চালান: 
from google_auth_oauthlib.flow import InstalledAppFlow

# Set your Client ID and Secret
CLIENT_ID = "INSERT_YOUR_CLIENT_ID_HERE"
CLIENT_SECRET = "INSERT_YOUR_CLIENT_SECRET_HERE"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    client_config = {
        "installed": {
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
            "token_uri": "https://oauth2.googleapis.com/token",
        }
    }
    
    # Initialize the flow
    flow = InstalledAppFlow.from_client_config(client_config, SCOPES)
    
    # Run the local server flow to prompt the user to log in
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

৬. ক্লায়েন্ট লাইব্রেরি এবং ক্রেডেনশিয়াল সেটআপ

গুগল আনুষ্ঠানিকভাবে সমর্থিত ক্লায়েন্ট লাইব্রেরি সরবরাহ করে যা gRPC এন্ডপয়েন্টগুলির সাথে প্রমাণীকরণ, সিরিয়ালাইজেশন এবং যোগাযোগ পরিচালনা করে।

সমর্থিত ভাষা

  • পাইথন: pip install google-ads
  • জাভা: Maven বা Gradle এর মাধ্যমে উপলব্ধ
  • PHP: composer require googleads/google-ads-php
  • .NET: Install-Package Google.Ads.GoogleAds
  • রুবি: gem install google-ads-googleads

কনফিগারেশন ফাইল ( google-ads.yaml )

আপনার ক্রেডেনশিয়াল সহ একটি কনফিগারেশন ফাইল তৈরি করুন। ডিফল্টরূপে, ক্লায়েন্ট লাইব্রেরির ইনিশিয়ালাইজেশন মেথড (যেমন, GoogleAdsClient.load_from_storage() ) স্বয়ংক্রিয়ভাবে দুটি স্থানে google-ads.yaml ফাইলটি অনুসন্ধান করবে:

  1. বর্তমান ওয়ার্কিং ডিরেক্টরি যেখান থেকে আপনার স্ক্রিপ্টটি চালানো হয়।
  2. আপনার ব্যবহারকারীর হোম ডিরেক্টরি (লিনাক্স/ম্যাকওএস-এ ~ অথবা উইন্ডোজ-এ %HOMEPATH% )।

যদি আপনি ফাইলটি কোনো কাস্টম লোকেশনে সংরক্ষণ করেন, তাহলে আপনি ইনিশিয়ালাইজেশন মেথডে পাথটি স্পষ্টভাবে পাস করতে পারেন (যেমন, load_from_storage("path/to/google-ads.yaml") )।

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

৭. আপনার প্রথম এপিআই কলটি করুন

আপনার অনবোর্ডিং সেটআপ যাচাই করতে, আপনার টেস্ট অ্যাকাউন্ট থেকে বিদ্যমান ক্যাম্পেইনগুলো আনার জন্য একটি কুইকস্টার্ট স্ক্রিপ্ট চালান।

পাইথন স্ক্রিপ্টের উদাহরণ ( quickstart.py ) 

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

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(f"Campaign with ID {row.campaign.id} and name '{row.campaign.name}' was found.")

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the current working directory
    # or the user's home directory (~). You can also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens)
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    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)

৮. সর্বোত্তম অনুশীলন এবং সংস্থানসমূহ

  • লগিং: আপনার ক্লায়েন্ট লাইব্রেরিতে বিস্তারিত লগিং সক্ষম করুন যাতে অনুরোধ/প্রতিক্রিয়া আইডি ( request-id ) সংগ্রহ করা যায়, যা গুগলের কাছে সহায়তা চাওয়ার সময় অপরিহার্য।
  • ত্রুটি পরিচালনা: GoogleAdsException জন্য শক্তিশালী ত্রুটি পরিচালনা ব্যবস্থা প্রয়োগ করুন, বিশেষত রেট লিমিট ( RESOURCE_TEMPORARILY_EXHAUSTED ) পরিচালনা করুন।
  • অফিসিয়াল ডকুমেন্টেশন: গুগল অ্যাডস এপিআই ডেভেলপার ডক্স
  • ক্লায়েন্ট লাইব্রেরি ও কোড স্যাম্পল: গিটহাব গুগল অ্যাডস রিপোজিটরি