واجهة برمجة تطبيقات "إدارة العلامات من Google" - دليل المطوّرين

يرشدك دليل المطوّرين هذا إلى الخطوات المطلوبة للوصول إلى الكيانات وإنشائها وإدارتها ضمن حساب على أداة "إدارة العلامات من Google" من خلال الإصدار 2 من واجهة برمجة التطبيقات الخاصة بأداة "إدارة العلامات من Google".

مقدمة

يوجّهك هذا الدليل خلال خطوات مختلفة للوصول إلى حساب على "مدير علامات Google" وإعداده. بعد الانتهاء من هذه الدورة التدريبية، سيكون لديك فهم أساسي لكيفية تنفيذ المهام التالية:

• أنشئ عنصر خدمة في أداة "إدارة العلامات من Google".
• مصادقة مستخدم ومنحه الإذن
• استخدِم Tag Manager API للوصول إلى الموارد وإدارتها.

قبل البدء

قبل البدء في هذا الدليل، ننصحك بالتعرّف على أداة "إدارة العلامات من Google" من خلال الانتقال إلى مركز مساعدة "إدارة العلامات من Google".

استخدام حساب اختباري

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

تنبيه: عند تنفيذ عمليات مدمرة باستخدام واجهة برمجة التطبيقات، لن تظهر أي تحذيرات أو تأكيدات، ولن يكون هناك خيار للتراجع. استخدِم حسابًا تجريبيًا لاختبار الرمز والتحقّق منه قبل العمل باستخدام حسابات نشطة.

اختيار لغة

اختَر لغة البرمجة التي تريد اتّباع الأمثلة فيها:

Python

تم اختيار Python لجميع مقتطفات الرموز البرمجية في هذا الدليل.

JavaScript

تم اختيار JavaScript لجميع مقتطفات الرموز في هذا الدليل.

نظرة عامة حول البرنامج

برنامج المثال المضمّن في هذا الدليل هو تطبيق سطر أوامر. عند توفير رقم تعريف حساب، يعثر التطبيق على حاوية باسم Greetings وينشئ علامة Universal Analytics في تلك الحاوية. عندما يزور المستخدم hello-world.html، ترسل العلامة نتيجة مشاهدة صفحة.

لتطوير هذا التطبيق، عليك اتّباع الخطوات التالية:

1. إعداد بيئة التطوير والمشروع في Google API Console
2. أنشئ عنصر خدمة في أداة "إدارة العلامات من Google".
   1. منح إذن الوصول إلى حساب على "إدارة العلامات من Google"
   2. أنشئ عنصر خدمة في أداة "إدارة العلامات من Google".
3. إرسال طلب بحث إلى واجهة برمجة التطبيقات والتعامل مع الردّ وإخراج النتائج
   1. الحصول على عنصر خدمة Tag Manager تمّت تهيئته
   2. استخدِم عنصر خدمة Tag Manager للاستعلام عن واجهة برمجة التطبيقات الخاصة بأداة Tag Manager لتنفيذ المهام التالية:
      1. استرداد الحاوية Greetings لحساب Google Tag Manager الذي تمّت المصادقة عليه
      2. أنشئ مساحة عمل جديدة.
      3. أنشئ علامة Universal Analytics.
      4. أنشئ عامل التشغيل لتفعيل العلامة.
      5. عدِّل العلامة ليتم تنشيطها عند تشغيل العامل المشغِّل.

إعداد بيئة التطوير والمشروع

إنشاء حاوية التحيات

يفترض هذا الدليل أنّ لديك حسابًا على أداة "إدارة العلامات من Google" يتضمّن حاوية باسم التحيات. اتّبِع التعليمات الواردة في الإعداد وسير العمل (على الويب) لإنشاء حساب وحاوية باسم التحيات.

تثبيت مكتبة برامج

قبل البدء، ثبِّت مكتبة برامج Google APIs وأعِد ضبطها.

إنشاء مشروع وضبط إعداداته في Google API Console

لبدء استخدام Tag Manager API، عليك أولاً استخدام أداة الإعداد التي تساعدك على إنشاء مشروع في وحدة تحكّم Google API وتفعيل واجهة برمجة التطبيقات.

يستخدم هذا الدليل مسار مصادقة تطبيق مثبَّت. اتّبِع التعليمات أدناه لإنشاء بيانات اعتماد مشروعك. عندما يُطلب منك ذلك، اختَر Installed Application في نوع التطبيق وOther في نوع التطبيق المثبَّت.

1. من صفحة "بيانات الاعتماد"، انقر على إنشاء بيانات اعتماد > معرّف عميل OAuth لإنشاء بيانات اعتماد OAuth 2.0 أو على إنشاء بيانات اعتماد > مفتاح حساب الخدمة لإنشاء حساب خدمة.
2. إذا أنشأت معرّف عميل OAuth، اختَر نوع تطبيقك.
3. املأ النموذج وانقر على إنشاء.

تظهر الآن معرّفات العملاء ومفاتيح حسابات الخدمة الخاصة بتطبيقك في صفحة "بيانات الاعتماد". للحصول على التفاصيل، انقر على معرّف عميل. تختلف المَعلمات حسب نوع المعرّف، ولكن قد تتضمّن عنوان البريد الإلكتروني أو سر العميل أو مصادر JavaScript أو معرّفات الموارد المنتظمة (URI) لإعادة التوجيه.

نزِّل تفاصيل العميل من خلال النقر على الزر تنزيل JSON. أعِد تسمية هذا الملف إلى client_secrets.json. سيتم استخدام هذا الملف لاحقًا لأغراض المصادقة.

إنشاء عنصر خدمة في أداة "إدارة العلامات من Google"

كائن service في "إدارة العلامات من Google" هو ما ستستخدمه لتقديم طلبات إلى واجهة برمجة التطبيقات.

في ما يلي الخطوات المطلوبة لإنشاء عنصر خدمة "إدارة العلامات من Google":

1. منح إذن الوصول إلى حساب على "إدارة العلامات من Google"
2. إنشاء مثيل لعنصر خدمة Tag Manager

منح إذن الوصول إلى حساب على "إدارة العلامات من Google"

عندما يبدأ المستخدم تطبيقًا تم إنشاؤه باستخدام Google Tag Manager API، عليه منح التطبيق إذن الوصول إلى حسابه على Google Tag Manager. تُعرف هذه العملية باسم التفويض. الطريقة المقترَحة لمنح المستخدمين الإذن هي OAuth 2.0. لمزيد من المعلومات، يمكنك الاطّلاع على تفويض الوصول إلى واجهة برمجة التطبيقات في "إدارة العلامات من Google".

يستخدم الرمز أدناه تفاصيل المشروع والعميل التي تم إنشاؤها أعلاه للمصادقة على مستخدم التطبيق ويطلب منه الإذن بالوصول إلى أداة "إدارة العلامات من Google" نيابةً عنه.

سيحاول التطبيق فتح المتصفّح التلقائي وتوجيه المستخدم إلى عنوان URL مستضاف على google.com. سيُطلب من المستخدم تسجيل الدخول ومنح التطبيق إذن الوصول إلى حسابه على "إدارة العلامات من Google". بعد منح الإذن، سيحاول التطبيق قراءة رمز من نافذة المتصفّح، ثم إغلاق النافذة.

ملاحظة: في حال حدوث خطأ، سيطلب التطبيق من المستخدم إدخال رمز التفويض في سطر الأوامر.

Python

"""Access and manage a Google Tag Manager account."""

import argparse
import sys

import httplib2

from apiclient.discovery import build
from oauth2client import client
from oauth2client import file
from oauth2client import tools


def GetService(api_name, api_version, scope, client_secrets_path):
  """Get a service that communicates to a Google API.

  Args:
    api_name: string The name of the api to connect to.
    api_version: string The api version to connect to.
    scope: A list of strings representing the auth scopes to authorize for the
      connection.
    client_secrets_path: string A path to a valid client secrets file.

  Returns:
    A service that is connected to the specified API.
  """
  # Parse command-line arguments.
  parser = argparse.ArgumentParser(
      formatter_class=argparse.RawDescriptionHelpFormatter,
      parents=[tools.argparser])
  flags = parser.parse_args([])

  # Set up a Flow object to be used if we need to authenticate.
  flow = client.flow_from_clientsecrets(
      client_secrets_path, scope=scope,
      message=tools.message_if_missing(client_secrets_path))

  # Prepare credentials, and authorize HTTP object with them.
  # If the credentials don't exist or are invalid run through the native client
  # flow. The Storage object will ensure that if successful the good
  # credentials will get written back to a file.
  storage = file.Storage(api_name + '.dat')
  credentials = storage.get()
  if credentials is None or credentials.invalid:
    credentials = tools.run_flow(flow, storage, flags)
  http = credentials.authorize(http=httplib2.Http())

  # Build the service object.
  service = build(api_name, api_version, http=http)

  return service

def main(argv):
  # Define the auth scopes to request.
  scope = ['https://www.googleapis.com/auth/tagmanager.edit.containers']

  # Authenticate and construct service.
  service = GetService('tagmanager', 'v2', scope, 'client_secrets.json')


if __name__ == '__main__':
  main(sys.argv)
    

JavaScript

<html>
  <head>
    <script type="text/javascript">

    // Your Client ID can be retrieved from your project in the Google
    // Developer Console, https://console.developers.google.com
    var CLIENT_ID = TODO;
    var SCOPES = [
      'https://www.googleapis.com/auth/tagmanager.manage.accounts',
      'https://www.googleapis.com/auth/tagmanager.edit.containers',
      'https://www.googleapis.com/auth/tagmanager.delete.containers',
      'https://www.googleapis.com/auth/tagmanager.edit.containerversions',
      'https://www.googleapis.com/auth/tagmanager.manage.users',
      'https://www.googleapis.com/auth/tagmanager.publish'
    ];

    // Parameter values used by the script
    ACCOUNT_PATH = TODO; // such as: 'accounts/555555';
    CONTAINER_NAME = 'Greetings';
    WORKSPACE_NAME = 'Example workspace';

    /**
     * Check if current user has authorization for this application.
     *
     * @param {bool} immediate Whether login should use the "immediate mode", which
     *     causes the security token to be refreshed behind the scenes with no UI.
     */
    function checkAuth(immediate) {
      var authorizeCheckPromise = new Promise((resolve) => {
        gapi.auth.authorize(
          { client_id: CLIENT_ID, scope: SCOPES.join(' '), immediate: immediate },
          resolve);
      });
      authorizeCheckPromise
          .then(handleAuthResult)
          .then(loadTagManagerApi)
          .then(runTagManagerExample)
          .catch(() => {
            console.log('You must authorize any access to the api.');
          });
    }

    /**
     * Check if current user has authorization for this application.
     */
    function checkAuth() {
      checkAuth(true);
    }

    /**
     * Initiate auth flow in response to user clicking authorize button.
     *
     * @param {Event} event Button click event.
     * @return {boolean} Returns false.
     */
    function handleAuthClick(event) {
      checkAuth();
      return false;
    }

    /**
     * Handle response from authorization server.
     *
     * @param {Object} authResult Authorization result.
     * @return {Promise} A promise to call resolve if authorize or redirect to a
     *   login flow.
     */
    function handleAuthResult(authResult) {
      return new Promise((resolve, reject) => {
        var authorizeDiv = document.getElementById('authorize-div');
        if (authResult && !authResult.error) {
          // Hide auth UI, then load client library.
          authorizeDiv.style.display = 'none';
          resolve();
        } else {
          // Show auth UI, allowing the user to initiate authorization by
          // clicking authorize button.
          authorizeDiv.style.display = 'inline';
          reject();
        }
      });
    }

    /**
     * Load Tag Manager API client library.
     *
     * @return {Promise} A promise the load the Tag Manager API library.
     */
    function loadTagManagerApi() {
      return new Promise((resolve, reject) => {
        console.log('Load Tag Manager api');
        gapi.client.load('tagmanager', 'v2', resolve);
      });
    }

    /**
     * Interacts with the tagmanager api v2 to create a container, workspace,
     * trigger, and tag.
     *
     * @return {Promise} A promise to run the Tag Manager example.
     */
    function runTagManagerExample() {
      return new Promise((resolve, reject) => {
        console.log('Running Tag Manager Example.');
        resolve();
      });
    }

    /**
     * Logs an error message to the console.
     *
     * @param {string|Object} error The error to log to the console.
     */
    function handleError(error) {
      console.log('Error when interacting with GTM API');
      console.log(error);
    }

    /**
     * Wraps an API request into a promise.
     *
     * @param {Object} a request to the API.
     * @return {Promise} A promise to execute the API request.
     */
    function requestPromise(request) {
      return new Promise((resolve, reject) => {
        request.execute((response) => {
          if (response.code) {
            reject(response);
          }
          resolve(response);
        });
      });
    }
    </script>

    <script src="https://apis.google.com/js/client.js?onload=checkAuth">
    </script>
  </head>
  <body>
    <div id="authorize-div" style="display: none">
      <span>Authorize access to Tag Manager API</span>
      <!--Button for the user to click to initiate auth sequence -->
      <button id="authorize-button" onclick="handleAuthClick(event)">
        Authorize
      </button>
    </div>
    <pre id="output"></pre>
  </body>
</html>

    

طلب بيانات من Tag Manager API

يمكن استخدام عنصر خدمة Tag Manager لطلب بيانات من واجهة برمجة التطبيقات الخاصة بأداة Tag Manager. يجب اتّباع الخطوات التالية لتنفيذ البرنامج التجريبي:

1. استرداد حاوية "رسائل الترحيب"
2. إنشاء علامة Universal Analytics
3. إنشاء المشغّل لتنشيط العلامة
4. تعديل العلامة ليتم تنشيطها عند تشغيل العامل المشغِّل

1- استرداد حاوية التحيات

توضّح الدالة التالية كيف يمكن استخدام عنصر خدمة "إدارة العلامات من Google" للاستعلام من واجهة برمجة التطبيقات الخاصة بأداة "إدارة العلامات من Google" من أجل إدراج جميع حاويات الحساب واسترداد الحاوية التي تحمل الاسم Greetings.

يمكنك العثور على حسابك على "إدارة العلامات من Google" في شريط العناوين في واجهة الويب لأداة "إدارة العلامات من Google". على سبيل المثال، رقم تعريف الحساب في عنوان URL https://tagmanager.google.com/#/admin/accounts/112233/containers/2292948/users هو 112233.

Python

def FindGreetingsContainer(service, account_path):
  """Find the greetings container.

  Args:
    service: the Tag Manager service object.
    account_path: the path of the Tag Manager account from which to retrieve the
      Greetings container.

  Returns:
    The greetings container if it exists, or None if it does not.
  """
  # Query the Tag Manager API to list all containers for the given account.
  container_wrapper = service.accounts().containers().list(
      parent=account_path).execute()

  # Find and return the Greetings container if it exists.
  for container in container_wrapper['container']:
    if container['name'] == 'Greetings':
      return container
  return None
    

JavaScript

/**
 * Returns the greetings container if it exists.
 *
 * @param {string} accountPath The account which contains the Greetings
 * container.
 * @return {Promise} A promise to find the greetings container.
 */
function findContainer(accountPath, containerName) {
  console.log('Finding container in account:' + accountPath);
  var request = gapi.client.tagmanager.accounts.containers.list({
    'parent': accountPath
  });
  return requestPromise(request)
      .then((response) => {
        var containers = response.container || [];
        var container =
            containers.find((container) => container.name === containerName);
        return container ||
            Promise.reject('Unable to find ' + containerName +' container.');
      });
}
    

بعد ذلك، عدِّل فرع التنفيذ الرئيسي للبرنامج لاستدعاء الدالة findGreetingsContainer مع توفير accountId "إدارة العلامات من Google". على سبيل المثال:

Python

def main(argv):
  # Get tag manager account ID from command line.
  assert len(argv) == 2 and 'usage: gtm-api-hello-world.py <account_id>'
  account_id = str(argv[1])
  account_path = 'accounts/%s' % account_id

  # Define the auth scopes to request.
  scope = ['https://www.googleapis.com/auth/tagmanager.edit.containers']

  # Authenticate and construct service.
  service = GetService('tagmanager', 'v2', scope, 'client_secrets.json')

  # Find the greetings container.
  container = FindGreetingsContainer(service, account_path)

if __name__ == '__main__':
  main(sys.argv)
    

JavaScript

/**
 * Interacts with the tagmanager api v2 to create a container, workspace,
 * trigger, and tag.
 *
 * @return {Promise} A promise to run the tag manager example.
 */
function runTagManagerExample() {
  return new Promise((resolve, reject) => {
    console.log('Running Tag Manager Example.');
    var trigger = null;
    var workspace = null;
    findContainer(ACCOUNT_PATH, CONTAINER_NAME)
        .catch(handleError);
    resolve();
  });
}
    

2. إنشاء مساحة عمل جديدة

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

Python

def CreateWorkspace(service, container):
    """Creates a workspace named 'my workspace'.

    Args:
      service: the Tag Manager service object.
      container: the container to insert the workspace within.

    Returns:
      The created workspace.
    """
    return service.accounts().containers().workspaces().create(
        parent=container['path'],
        body={
            'name': 'my workspace',
        }).execute()
    

JavaScript

/**
 * Creates a workspace in the Greetings container.
 *
 * @param {Object} container The container to create a new workspace.
 * @return {Promise} A promise to create a workspace.
 */
function createWorkspace(container) {
  console.log('Creating workspace in container:' + container.path);
  var request = gapi.client.tagmanager.accounts.containers.workspaces.create(
    { 'parent': container.path },
    { name: WORKSPACE_NAME, description: 'my workspace created via api' });
  return requestPromise(request);
}

    

3- إنشاء علامة Universal Analytics

يستخدم مقتطف الرمز البرمجي التالي واجهة برمجة التطبيقات الخاصة بأداة "إدارة العلامات من Google" لإنشاء علامة Universal Analytics. يمكنك مراجعة مرجع طريقة إنشاء العلامات للاطّلاع على قائمة بالخصائص المطلوبة والاختيارية التي يمكن ضبطها عند إنشاء علامة، ومرجع قاموس العلامات للاطّلاع على قائمة بالخصائص لكل نوع من أنواع العلامات.

Python

def CreateHelloWorldTag(service, workspace, tracking_id):
  """Create the Universal Analytics Hello World Tag.

  Args:
    service: the Tag Manager service object.
    workspace: the workspace to create a tag within.
    tracking_id: the Universal Analytics tracking ID to use.

  Returns:
    The created tag.
  """

  hello_world_tag = {
      'name': 'Universal Analytics Hello World',
      'type': 'ua',
      'parameter': [{
          'key': 'trackingId',
          'type': 'template',
          'value': str(tracking_id),
      }],
  }

  return service.accounts().containers().workspaces().tags().create(
      parent=workspace['path'],
      body=hello_world_tag).execute()

    

JavaScript

/**
 * Creates a universal analytics tag.
 *
 * @param {Object} workspace The workspace to create the tag
 * @return {Promise} A promise to create a hello world tag.
 */
function createHelloWorldTag(workspace) {
  console.log('Creating hello world tag');
  var helloWorldTag = {
    'name': 'Universal Analytics Hello World',
    'type': 'ua',
    'parameter':
    [{ 'key': 'trackingId', 'type': 'template', 'value': 'UA-1234-5' }],
  };
  var request =
    gapi.client.tagmanager.accounts.containers.workspaces.tags.create(
      { 'parent': workspace.path }, helloWorldTag);
  return requestPromise(request);
}

    

4. إنشاء المشغّل لتنشيط العلامة

بعد إنشاء علامة، الخطوة التالية هي إنشاء مشغّل سيتم تفعيله في أي صفحة.

سيتم تسمية المشغّل Hello World Trigger وسيتم تنشيطه عند عرض أي صفحة. على سبيل المثال:

Python

def CreateHelloWorldTrigger(service, workspace):
  """Create the Hello World Trigger.

  Args:
    service: the Tag Manager service object.
    workspace: the workspace to create the trigger within.

  Returns:
    The created trigger.
  """

  hello_world_trigger = {
      'name': 'Hello World Rule',
      'type': 'PAGEVIEW'
  }

  return service.accounts().containers().workspaces().triggers().create(
      parent=workspace['path'],
      body=hello_world_trigger).execute()
    

JavaScript

/**
 * Creates a page view trigger.
 *
 * @param {Object} workspace The workspace to create the trigger in.
 * @return {Promise} A promise to create a page view trigger.
 */
function createHelloWorldTrigger(workspace) {
  console.log('Creating hello world trigger in workspace');
  var helloWorldTrigger = { 'name': 'Hello World Trigger', 'type': 'PAGEVIEW' };
  var request =
    gapi.client.tagmanager.accounts.containers.workspaces.triggers.create(
      { 'parent': workspace.path }, helloWorldTrigger);
  return requestPromise(request);
}

    

5- تعديل العلامة ليتم تنشيطها عند تشغيل العامل المشغِّل

بعد إنشاء علامة وعامل مشغّل، يجب ربطهما ببعضهما. لإجراء ذلك، أضِف triggerId إلى قائمة firingTriggerIds المرتبطة بالعلامة. على سبيل المثال:

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

Python

def UpdateHelloWorldTagWithTrigger(service, tag, trigger):
  """Update a Tag with a Trigger.

  Args:
    service: the Tag Manager service object.
    tag: the tag to associate with the trigger.
    trigger: the trigger to associate with the tag.
  """
  # Get the tag to update.
  tag = service.accounts().containers().workspaces().tags().get(
      path=tag['path']).execute()

  # Update the Firing Trigger for the Tag.
  tag['firingTriggerId'] = [trigger['triggerId']]

  # Update the Tag.
  response = service.accounts().containers().workspaces().tags().update(
      path=tag['path'],
      body=tag).execute()
    

JavaScript

/**
 * Updates a tag to fire on a particular trigger.
 *
 * @param {Object} tag The tag to update.
 * @param {Object} trigger The trigger which causes the tag to fire.
 * @return {Promise} A promise to update a tag to fire on a particular trigger.
 */
function updateHelloWorldTagWithTrigger(tag, trigger) {
  console.log('Update hello world tag with trigger');
  tag['firingTriggerId'] = [trigger.triggerId];
  var request =
    gapi.client.tagmanager.accounts.containers.workspaces.tags.update(
      { 'path': tag.path }, tag);
  return requestPromise(request);
}
    

بعد ذلك، عدِّل فرع التنفيذ الرئيسي للبرنامج لاستدعاء وظيفتَي الإنشاء والتعديل. على سبيل المثال:

Python

def main(argv):
  # Get tag manager account ID from command line.
  assert len(argv) == 2 and 'usage: gtm-api-hello-world.py <account_id>'
  account_id = str(argv[1])
  account_path = 'accounts/%s' % account_id

  # Define the auth scopes to request.
  scope = ['https://www.googleapis.com/auth/tagmanager.edit.containers']

  # Authenticate and construct service.
  service = GetService('tagmanager', 'v2', scope, 'client_secrets.json')

  # Find the greetings container.
  container = FindGreetingsContainer(service, account_path)

  # Create a new workspace.
  workspace = CreateWorkspace(service, container)

  # Create the hello world tag.
  tag = CreateHelloWorldTag(
      service, workspace, 'UA-1234-5')

  # Create the hello world Trigger.
  trigger = CreateHelloWorldTrigger(
      service, workspace)

  # Update the hello world tag to fire based on the hello world tag.
  UpdateHelloWorldTagWithTrigger(service, tag, trigger)
if __name__ == '__main__':
  main(sys.argv)
    

JavaScript

/**
 * Interacts with the tagmanager api v2 to create a container, workspace,
 * trigger, and tag.
 *
 * @return {Promise} A promise to run the tag manager example.
 */
function runTagManagerExample() {
  return new Promise((resolve, reject) => {
    console.log('Running Tag Manager Example.');
    var trigger = null;
    var workspace = null;
    findContainer(ACCOUNT_PATH, CONTAINER_NAME)
        .then(createWorkspace)
        .then((createdWorkspace) => {
          workspace = createdWorkspace;
          return createHelloWorldTrigger(workspace);
        })
        .then((createdTrigger) => {
          trigger = createdTrigger;
          return createHelloWorldTag(workspace);
        })
        .then((createdTag) => {
          return updateHelloWorldTagWithTrigger(createdTag, trigger);
        })
        .catch(handleError);
    resolve();
  });
}

    

مثال كامل

وسِّع هذا القسم للاطّلاع على مثال الرمز البرمجي الكامل لجميع الخطوات الواردة في الدليل.

Python

"""Access and manage a Google Tag Manager account."""

import argparse
import sys

import httplib2

from apiclient.discovery import build
from oauth2client import client
from oauth2client import file
from oauth2client import tools


def GetService(api_name, api_version, scope, client_secrets_path):
  """Get a service that communicates to a Google API.

  Args:
    api_name: string The name of the api to connect to.
    api_version: string The api version to connect to.
    scope: A list of strings representing the auth scopes to authorize for the
      connection.
    client_secrets_path: string A path to a valid client secrets file.

  Returns:
    A service that is connected to the specified API.
  """
  # Parse command-line arguments.
  parser = argparse.ArgumentParser(
      formatter_class=argparse.RawDescriptionHelpFormatter,
      parents=[tools.argparser])
  flags = parser.parse_args([])

  # Set up a Flow object to be used if we need to authenticate.
  flow = client.flow_from_clientsecrets(
      client_secrets_path, scope=scope,
      message=tools.message_if_missing(client_secrets_path))

  # Prepare credentials, and authorize HTTP object with them.
  # If the credentials don't exist or are invalid run through the native client
  # flow. The Storage object will ensure that if successful the good
  # credentials will get written back to a file.
  storage = file.Storage(api_name + '.dat')
  credentials = storage.get()
  if credentials is None or credentials.invalid:
    credentials = tools.run_flow(flow, storage, flags)
  http = credentials.authorize(http=httplib2.Http())

  # Build the service object.
  service = build(api_name, api_version, http=http)

  return service

def FindGreetingsContainer(service, account_path):
  """Find the greetings container.

  Args:
    service: the Tag Manager service object.
    account_path: the path of the Tag Manager account from which to retrieve the
      Greetings container.

  Returns:
    The greetings container if it exists, or None if it does not.
  """
  # Query the Tag Manager API to list all containers for the given account.
  container_wrapper = service.accounts().containers().list(
      parent=account_path).execute()

  # Find and return the Greetings container if it exists.
  for container in container_wrapper['container']:
    if container['name'] == 'Greetings':
      return container
  return None

def CreateWorkspace(service, container):
    """Creates a workspace named 'my workspace'.

    Args:
      service: the Tag Manager service object.
      container: the container to insert the workspace within.

    Returns:
      The created workspace.
    """
    return service.accounts().containers().workspaces().create(
        parent=container['path'],
        body={
            'name': 'my workspace',
        }).execute()

def CreateHelloWorldTag(service, workspace, tracking_id):
  """Create the Universal Analytics Hello World Tag.

  Args:
    service: the Tag Manager service object.
    workspace: the workspace to create a tag within.
    tracking_id: the Universal Analytics tracking ID to use.

  Returns:
    The created tag.
  """

  hello_world_tag = {
      'name': 'Universal Analytics Hello World',
      'type': 'ua',
      'parameter': [{
          'key': 'trackingId',
          'type': 'template',
          'value': str(tracking_id),
      }],
  }

  return service.accounts().containers().workspaces().tags().create(
      parent=workspace['path'],
      body=hello_world_tag).execute()


def CreateHelloWorldTrigger(service, workspace):
  """Create the Hello World Trigger.

  Args:
    service: the Tag Manager service object.
    workspace: the workspace to create the trigger within.

  Returns:
    The created trigger.
  """

  hello_world_trigger = {
      'name': 'Hello World Rule',
      'type': 'PAGEVIEW'
  }

  return service.accounts().containers().workspaces().triggers().create(
      parent=workspace['path'],
      body=hello_world_trigger).execute()

def UpdateHelloWorldTagWithTrigger(service, tag, trigger):
  """Update a Tag with a Trigger.

  Args:
    service: the Tag Manager service object.
    tag: the tag to associate with the trigger.
    trigger: the trigger to associate with the tag.
  """
  # Get the tag to update.
  tag = service.accounts().containers().workspaces().tags().get(
      path=tag['path']).execute()

  # Update the Firing Trigger for the Tag.
  tag['firingTriggerId'] = [trigger['triggerId']]

  # Update the Tag.
  response = service.accounts().containers().workspaces().tags().update(
      path=tag['path'],
      body=tag).execute()

def main(argv):
  # Get tag manager account ID from command line.
  assert len(argv) == 2 and 'usage: gtm-api-hello-world.py <account_id>'
  account_id = str(argv[1])
  account_path = 'accounts/%s' % account_id

  # Define the auth scopes to request.
  scope = ['https://www.googleapis.com/auth/tagmanager.edit.containers']

  # Authenticate and construct service.
  service = GetService('tagmanager', 'v2', scope, 'client_secrets.json')

  # Find the greetings container.
  container = FindGreetingsContainer(service, account_path)

  # Create a new workspace.
  workspace = CreateWorkspace(service, container)

  # Create the hello world tag.
  tag = CreateHelloWorldTag(
      service, workspace, 'UA-1234-5')

  # Create the hello world Trigger.
  trigger = CreateHelloWorldTrigger(
      service, workspace)

  # Update the hello world tag to fire based on the hello world tag.
  UpdateHelloWorldTagWithTrigger(service, tag, trigger)
  
if __name__ == '__main__':
  main(sys.argv)

    

JavaScript

<html>
  <head>
    <script type="text/javascript">

    // Your Client ID can be retrieved from your project in the Google
    // Developer Console, https://console.developers.google.com
    var CLIENT_ID = TODO;
    var SCOPES = [
      'https://www.googleapis.com/auth/tagmanager.manage.accounts',
      'https://www.googleapis.com/auth/tagmanager.edit.containers',
      'https://www.googleapis.com/auth/tagmanager.delete.containers',
      'https://www.googleapis.com/auth/tagmanager.edit.containerversions',
      'https://www.googleapis.com/auth/tagmanager.manage.users',
      'https://www.googleapis.com/auth/tagmanager.publish'
    ];

    // Parameter values used by the script
    ACCOUNT_PATH = TODO; // such as: 'accounts/555555';
    CONTAINER_NAME = 'Greetings';
    WORKSPACE_NAME = 'Example workspace';

    /**
     * Check if current user has authorization for this application.
     *
     * @param {bool} immediate Whether login should use the "immediate mode",
     *     which causes the security token to be refreshed behind the scenes
     *     with no UI.
     */
    function checkAuth(immediate) {
      var authorizeCheckPromise = new Promise((resolve) => {
        gapi.auth.authorize(
          { client_id: CLIENT_ID, scope: SCOPES.join(' '), immediate: immediate },
          resolve);
      });
      authorizeCheckPromise
          .then(handleAuthResult)
          .then(loadTagManagerApi)
          .then(runTagManagerExample)
          .catch(() => {
            console.log('You must authorize any access to the api.');
          });
    }

    /**
     * Check if current user has authorization for this application.
     */
    function checkAuth() {
      checkAuth(true);
    }

    /**
     * Initiate auth flow in response to user clicking authorize button.
     *
     * @param {Event} event Button click event.
     * @return {boolean} Returns false.
     */
    function handleAuthClick(event) {
      checkAuth();
      return false;
    }

    /**
     * Handle response from authorization server.
     *
     * @param {Object} authResult Authorization result.
     * @return {Promise} A promise to call resolve if authorize or redirect to a
     *   login flow.
     */
    function handleAuthResult(authResult) {
      return new Promise((resolve, reject) => {
        var authorizeDiv = document.getElementById('authorize-div');
        if (authResult && !authResult.error) {
          // Hide auth UI, then load client library.
          authorizeDiv.style.display = 'none';
          resolve();
        } else {
          // Show auth UI, allowing the user to initiate authorization by
          // clicking authorize button.
          authorizeDiv.style.display = 'inline';
          reject();
        }
      });
    }

    /**
     * Load Tag Manager API client library.

     * @return {Promise} A promise to load the tag manager api library.
     */
    function loadTagManagerApi() {
      return new Promise((resolve, reject) => {
        console.log('Load Tag Manager api');
        gapi.client.load('tagmanager', 'v2', resolve);
      });
    }

    /**
     * Interacts with the tagmanager api v2 to create a container,
     * workspace, trigger, and tag.
     *
     * @return {Promise} A promise to run the tag manager example.
     */
    function runTagManagerExample() {
      return new Promise((resolve, reject) => {
        console.log('Running Tag Manager Example.');
        var trigger = null;
        var workspace = null;
        findContainer(ACCOUNT_PATH, CONTAINER_NAME)
            .then(createWorkspace)
            .then((createdWorkspace) => {
              workspace = createdWorkspace;
              return createHelloWorldTrigger(workspace);
            })
            .then((createdTrigger) => {
              trigger = createdTrigger;
              return createHelloWorldTag(workspace);
            })
            .then((createdTag) => {
              return updateHelloWorldTagWithTrigger(createdTag, trigger);
            })
            .catch(handleError);
        resolve();
      });
    }

    /**
     * Returns the greetings container if it exists.
     *
     * @param {string} accountPath The account which contains the Greetings
     *     container.
     * @param {string} containerName The name of the container to find.
     * @return {Promise} A promise to find the greetings container.
     */
    function findContainer(accountPath, containerName) {
      console.log('Finding container in account:' + accountPath);
      var request = gapi.client.tagmanager.accounts.containers.list({
        'parent': accountPath
      });
      return requestPromise(request)
          .then((response) => {
            var containers = response.container || [];
            var container = containers.find(
                (container) => container.name === containerName);
            return container || Promise.reject(
                'Unable to find ' + containerName +' container.');
          });
    }

    /**
     * Creates a workspace in the Greetings container.
     *
     * @param {Object} container The container to create a new workspace.
     * @return {Promise} A promise to create a workspace.
     */
    function createWorkspace(container) {
      console.log('Creating workspace in container:' + container.path);
      var request = gapi.client.tagmanager.accounts.containers.workspaces.create(
        { 'parent': container.path },
        { name: WORKSPACE_NAME, description: 'my workspace created via api' });
      return requestPromise(request);
    }

    /**
     * Creates a page view trigger.
     *
     * @param {Object} workspace The workspace to create the trigger in.
     * @return {Promise} A promise to create a page view trigger.
     */
    function createHelloWorldTrigger(workspace) {
      console.log('Creating hello world trigger in workspace');
      var helloWorldTrigger =
          { 'name': 'Hello World Trigger', 'type': 'PAGEVIEW' };
      var request =
        gapi.client.tagmanager.accounts.containers.workspaces.triggers.create(
          { 'parent': workspace.path }, helloWorldTrigger);
      return requestPromise(request);
    }

    /**
    * Creates a universal analytics tag.
    *
    * @param {Object} workspace The workspace to create the tag
    * @return {Promise} A promise to create a hello world tag.
    */
    function createHelloWorldTag(workspace) {
      console.log('Creating hello world tag');
      var helloWorldTag = {
        'name': 'Universal Analytics Hello World',
        'type': 'ua',
        'parameter':
        [{ 'key': 'trackingId', 'type': 'template', 'value': 'UA-1234-5' }],
      };
      var request =
        gapi.client.tagmanager.accounts.containers.workspaces.tags.create(
          { 'parent': workspace.path }, helloWorldTag);
      return requestPromise(request);
    }

    /**
     * Updates a tag to fire on a particular trigger.
     *
     * @param {Object} tag The tag to update.
     * @param {Object} trigger The trigger which causes the tag to fire.
     * @return {Promise} A promise to update a tag to fire on a particular
     *    trigger.
     */
    function updateHelloWorldTagWithTrigger(tag, trigger) {
      console.log('Update hello world tag with trigger');
      tag['firingTriggerId'] = [trigger.triggerId];
      var request =
        gapi.client.tagmanager.accounts.containers.workspaces.tags.update(
          { 'path': tag.path }, tag);
      return requestPromise(request);
    }

    /**
     * Logs an error message to the console.
     *
     * @param {string|Object} error The error to log to the console.
     */
    function handleError(error) {
      console.log('Error when interacting with GTM API');
      console.log(error);
    }

    /**
     * Wraps an API request into a promise.
     *
     * @param {Object} request the API request.
     * @return {Promise} A promise to execute the api request.
     */
    function requestPromise(request) {
      return new Promise((resolve, reject) => {
        request.execute((response) => {
          if (response.code) {
            reject(response);
          }
          resolve(response);
        });
      });
    }
    </script>

    <script src="https://apis.google.com/js/client.js?onload=checkAuth">
    </script>
  </head>
  <body>
    <div id="authorize-div" style="display: none">
      <span>Authorize access to Tag Manager API</span>
      <!--Button for the user to click to initiate auth sequence -->
      <button id="authorize-button" onclick="handleAuthClick(event)">
        Authorize
      </button>
    </div>
    <pre id="output"></pre>
  </body>
</html>

    

الخطوات التالية

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

• مرجع واجهة برمجة التطبيقات: تعرَّف على واجهة برمجة التطبيقات والعمليات المتوافقة.
• مرجع المَعلمات – تعرَّف على كيفية ضبط مَعلمات العلامات والمتغيّرات.
• راجِع مرجع قاموس العلامات للاطّلاع على قائمة بالعلامات المتوافقة.
• راجِع مرجع قاموس المتغيرات للحصول على قائمة بالمتغيرات التي يمكن ضبطها.