يرشدك دليل مطوِّر البرامج هذا إلى الخطوات المطلوبة للوصول إلى الكيانات وإنشائها وإدارتها ضمن حساب على أداة "إدارة العلامات من Google" من خلال الإصدار الثاني من واجهة برمجة تطبيقات "إدارة العلامات من Google".
مقدمة
يوجِّهك هذا الدليل خلال الخطوات المختلفة للوصول إلى حساب على "إدارة العلامات من Google" وضبطه. عند الانتهاء، سيكون لديك فهمًا أساسيًا لكيفية القيام بالمهام التالية:
- أنشئ عنصر خدمة في أداة "إدارة العلامات من Google".
- مصادقة وتفويض مستخدم.
- يمكنك العمل باستخدام واجهة برمجة تطبيقات "إدارة العلامات من Google" للوصول إلى الموارد وإدارتها.
قبل البدء
قبل بدء الدليل، ننصحك بالاطّلاع على أداة "إدارة العلامات من Google" من خلال زيارة مركز مساعدة أداة "إدارة العلامات من Google".
استخدام حساب اختباري
إذا كنت تنوي استخدام واجهة برمجة تطبيقات "إدارة العلامات من Google" لإنشاء عناصر أو ضبطها أو حذفها، ننصحك بتنفيذ الرمز والتحقّق منه باستخدام حساب اختباري. سيساعدك استخدام حساب تجريبي على منعك من إجراء تغييرات غير مقصودة على الحساب النشط. بعد اختبار الرمز البرمجي والتأكد من عمله كما هو متوقع باستخدام الحساب التجريبي، يمكنك البدء في استخدام عملية التنفيذ مع حساباتك الحقيقية.
اختيار لغة
حدد لغة البرمجة التي تنوي اتباع الأمثلة بها:
Python
تم اختيار Python لجميع مقتطفات الرموز في هذا الدليل.
JavaScript
تمّ اختيار JavaScript لجميع مقتطفات الرموز في هذا الدليل.
نظرة عامة حول البرنامج
مثال البرنامج المتضمن في هذا الدليل هو تطبيق سطر أوامر. وبالنظر إلى رقم تعريف الحساب، يبحث التطبيق عن حاوية باسم تحيات المستخدم وينشئ علامة Universal Analytics في تلك الحاوية. عندما يزور المستخدم hello-world.html، فإن العلامة تُرسل نتيجة مشاهدة صفحة على الويب.
لتطوير هذا التطبيق، يجب اتّباع الخطوات التالية:
- عليك إعداد بيئة التطوير ومشروعك في وحدة تحكم واجهة Google API.
- أنشئ عنصر خدمة في أداة "إدارة العلامات من Google".
- امنح إذن الوصول إلى حساب "إدارة العلامات من Google".
- أنشئ عنصر خدمة في أداة "إدارة العلامات من Google".
- يمكنك إجراء طلب بحث في واجهة برمجة التطبيقات والتعامل مع الردّ وعرض النتائج.
- احصل على عنصر خدمة مهيأ لإدارة العلامات.
- استخدِم كائن خدمة "إدارة العلامات من Google" لإجراء طلب بحث في
واجهة برمجة تطبيقات "إدارة العلامات من Google" لتنفيذ المهام التالية:
- استرجع حاوية رسائل الترحيب لحساب "إدارة العلامات من Google" الذي تمت مصادقته.
- إنشاء مساحة عمل جديدة
- أنشئ علامة Universal Analytics.
- أنشئ المشغِّل لتنشيط العلامة.
- عدِّل العلامة لتنشيطها عند المشغِّل.
إعداد بيئة التطوير ومشروعك
أنشئ حاوية رسائل الترحيب.
يفترض هذا الدليل أن لديك حسابًا على أداة "إدارة العلامات من Google" بحاوية باسم رسائل الترحيب. اتّبِع تعليمات الإعداد وسير العمل (الويب) لإنشاء حساب وحاوية باسم رسائل الترحيب.
تثبيت مكتبة عملاء
قبل البدء، يمكنك تثبيت مكتبة عملاء Google APIs وإعدادها.
إنشاء مشروع وإعداده في وحدة التحكم في واجهة Google API
لبدء استخدام واجهة برمجة تطبيقات "إدارة العلامات من Google"، عليك أولاً استخدام أداة الإعداد التي ترشدك خلال خطوات إنشاء مشروع في وحدة تحكّم واجهة برمجة تطبيقات Google وتفعيل واجهة برمجة التطبيقات وإنشاء بيانات الاعتماد.
يستخدم هذا الدليل خطوات مصادقة التطبيقات المثبّتة. اتبع الإرشادات أدناه لإنشاء بيانات اعتماد مشروعك. اختَر Installed Application للسمة نوع
التطبيق وOther للخيار نوع التطبيق
المثبّت عندما يُطلب منك ذلك.
- من صفحة "بيانات الاعتماد"، انقر على إنشاء بيانات اعتماد > معرّف عميل OAuth لإنشاء بيانات اعتماد OAuth 2.0 أو إنشاء بيانات اعتماد > مفتاح حساب الخدمة لإنشاء حساب خدمة.
- إذا أنشأت معرِّف عميل OAuth، اختَر نوع التطبيق.
- املأ النموذج وانقر على إنشاء.
يتم الآن إدراج معرِّفات العميل ومفاتيح حساب الخدمة لتطبيقك في صفحة "بيانات الاعتماد". لمزيد من التفاصيل، انقر على معرِّف العميل، وتختلف المعلمات باختلاف نوع المعرّف، ولكنها قد تتضمن عنوان البريد الإلكتروني، أو سر العميل، أو أصول JavaScript، أو معرفات الموارد المنتظمة (URI) لإعادة التوجيه.
نزِّل تفاصيل العميل بالنقر على الزر تنزيل JSON. أعد تسمية هذا الملف إلى client_secrets.json. وسيتم استخدام هذا الملف
لاحقًا لأغراض المصادقة.
إنشاء عنصر خدمة في أداة "إدارة العلامات من Google"
عليك استخدام عنصر service في "إدارة العلامات من Google" لإجراء طلبات البيانات من واجهة برمجة التطبيقات.
في ما يلي الخطوات المطلوبة لإنشاء عنصر خدمة في أداة "إدارة العلامات من Google":
- امنح إذن الوصول إلى حساب "إدارة العلامات من Google".
- أنشئ مثيلاً لكائن خدمة "إدارة العلامات من Google".
تفويض الوصول إلى حساب "إدارة العلامات من Google"
عندما يبدأ أحد المستخدمين تطبيقًا تم إنشاؤه باستخدام Google Tag Manager API، يجب أن يمنحه التطبيق إذن الوصول إلى حسابه على أداة "إدارة العلامات من Google". وتُسمى هذه العملية الترخيص. الطريقة الموصى بها لتفويض المستخدمين هي 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>
إرسال طلب إلى واجهة برمجة تطبيقات "إدارة العلامات من Google"
يمكن استخدام كائن خدمة "إدارة العلامات من Google" لإجراء طلب بحث في واجهة برمجة تطبيقات "إدارة العلامات من Google". الخطوات التالية مطلوبة لتنفيذ البرنامج النموذجي:
- استرداد حاوية رسائل الترحيب
- إنشاء علامة Universal Analytics
- إنشاء المشغِّل لتنشيط العلامة
- تعديل العلامة لتنشيطها عند المشغِّل
1- استرجع حاوية رسائل الترحيب.
توضّح الوظيفة التالية كيفية استخدام عنصر خدمة "إدارة العلامات" للاستعلام عن واجهة برمجة تطبيقات "إدارة العلامات من Google" لإدراج جميع حاويات الحساب واسترداد الحاوية المسماة رسائل الترحيب.
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 وفقًا لأداة "إدارة العلامات من Google"
accountId. مثال:
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 المرتبطة بالعلامة. مثال:
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>
الخطوات التالية
والآن بعد أن تعرفت على كيفية عمل واجهة برمجة التطبيقات، هناك بعض الموارد الإضافية من أجلك:
- مرجع واجهة برمجة التطبيقات: للاطّلاع على معلومات حول واجهة برمجة التطبيقات والعمليات المتاحة
- مرجع المَعلمة : تعرَّف على معلومات عن ضبط المَعلمات للعلامات والمتغيّرات.
- راجِع مرجع قاموس العلامات للحصول على قائمة بالعلامات المتوافقة.
- راجِع مرجع قاموس المتغيّر للحصول على قائمة بالمتغيّرات التي يمكن ضبطها.