دليل الخطوات الأولى للهدف ج

يصف دليل المطوِّر هذا كيفية تنفيذ "إدارة العلامات من Google" في تطبيق متوافق مع الأجهزة الجوّالة.

مقدمة

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

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

  • إعدادات متنوعة لواجهة المستخدم وسلاسل عرض
  • الأحجام أو المواقع الجغرافية أو أنواع الإعلانات المعروضة في تطبيقك
  • إعدادات الألعاب

يمكن أيضًا تقييم قيم التهيئة في وقت التشغيل باستخدام القواعد، مع تمكين عمليات الضبط الديناميكية مثل:

  • استخدام حجم الشاشة لتحديد حجم بانر الإعلان
  • استخدام اللغة والموقع لضبط عناصر واجهة المستخدم

وتتيح أداة "إدارة العلامات من Google" أيضًا التنفيذ الديناميكي لعلامات التتبّع ووحدات البكسل في التطبيقات. يمكن للمطوّرين نقل الأحداث المهمة إلى طبقة بيانات وتحديد علامات التتبّع أو وحدات البكسل التي يجب تنشيطها لاحقًا. تتيح أداة "إدارة العلامات من Google" حاليًا العلامات التالية:

  • إحصاءات التطبيقات المتوافقة مع الأجهزة الجوّالة من Google
  • علامة استدعاء الدالة المخصّصة

قبل البدء

قبل استخدام دليل البدء هذا، ستحتاج إلى ما يلي:

إذا كنت مستخدمًا جديدًا لأداة "إدارة العلامات من Google"، ننصحك بالاطّلاع على مزيد من المعلومات عن الحاويات ووحدات الماكرو والقواعد (مركز المساعدة) قبل متابعة هذا الدليل.

البدء

سيوجِّه هذا القسم المطوّرين خلال سير عمل نموذجي على أداة "إدارة العلامات من Google":

  1. إضافة حزمة تطوير البرامج (SDK) لأداة "إدارة العلامات من Google" إلى مشروعك
  2. ضبط قيم الحاوية التلقائية
  3. فتح الحاوية
  4. الحصول على قيم الضبط من الحاوية
  5. دفع الأحداث إلى DataLayer
  6. معاينة الحاوية ونشرها

1- إضافة حزمة تطوير البرامج (SDK) لإدارة العلامات من Google إلى مشروعك

قبل استخدام حزمة تطوير البرامج (SDK) لإدارة العلامات من Google، يجب إضافة libGoogleAnalyticsServices.a وملفات عناوين "إدارة العلامات من Google" (GTM) من دليل Library لحزمة SDK إلى مشروعك.

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

  • CoreData.framework
  • SystemConfiguration.framework
  • libz.dylib
  • libsqlite3.dylib
  • libGoogleAnalyticsServices.a

إذا كنت تريد أن يصل تطبيقك إلى معرّف المعلِنين (IDFA) وعلامة التتبّع التي يوفّرها هذا الإطار من خلال وحدات ماكرو حزمة تطوير البرامج (SDK) لإدارة العلامات من Google، عليك أيضًا ربط المكتبات الإضافية التالية:

  • libAdIdAccess.a
  • AdSupport.framework

2. إضافة ملف حاوية تلقائي إلى مشروعك

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

لتنزيل برنامج ثنائي تلقائي للحاوية وإضافته إلى تطبيقك، اتّبِع الخطوات التالية:

  1. سجِّل الدخول إلى واجهة الويب لأداة "إدارة العلامات من Google".
  2. اختَر الإصدار للحاوية التي تريد تنزيلها.
  3. انقر على الزرّ تنزيل لاسترداد البرنامج الثنائي للحاوية.
  4. أضِف الملف الثنائي إلى الدليل الجذري لمشروعك وإلى مجلد "ملفات الدعم" في مشروعك.

يجب أن يكون اسم الملف التلقائي هو معرّف الحاوية (على سبيل المثال GTM-1234). بعد تنزيل الملف الثنائي، احرص على إزالة لاحقة الإصدار من اسم الملف للتأكّد من اتّباع اصطلاح التسمية الصحيح.

ويُنصح باستخدام الملف الثنائي، ولكن إذا لم تكن الحاوية تحتوي على قواعد أو علامات، يمكنك اختيار استخدام قائمة سمات بسيطة أو ملف JSON بدلاً من ذلك. يجب أن يكون الملف في الحزمة الرئيسية وأن يتّبع اصطلاح التسمية هذا: <Container_ID>.<plist|json>. على سبيل المثال، إذا كان رقم تعريف الحاوية هو GTM-1234، يمكنك تحديد قيم الحاوية التلقائية في ملف قائمة السمات باسم GTM-1234.plist.

3. فتح حاوية

قبل استرداد القيم من الحاوية، يجب أن يفتح تطبيقك الحاوية. سيؤدي فتح حاوية إلى تحميلها من القرص (إذا كان ذلك متاحًا)، أو طلبها من الشبكة (إذا لزم الأمر).

إنّ أسهل طريقة لفتح حاوية على iOS هي باستخدام openContainerWithId:tagManager:openType:timeout:notifier:، كما في المثال التالي:

// MyAppDelegate.h
// This example assumes this file is using ARC.
#import <UIKit/UIKit.h>

@class TAGManager;
@class TAGContainer;

@interface MyAppDelegate : UIResponder <UIApplicationDelegate>

@property (nonatomic, strong) TAGManager *tagManager;
@property (nonatomic, strong) TAGContainer *container;

@end


// MyAppDelegate.m
// This example assumes this file is using ARC.
#import "MyAppDelegate.h"
#import "TAGContainer.h"
#import "TAGContainerOpener.h"
#import "TAGManager.h"

@interface MyAppDelegate ()<TAGContainerOpenerNotifier>
@end

@implementation MyAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  self.tagManager = [TAGManager instance];

  // Optional: Change the LogLevel to Verbose to enable logging at VERBOSE and higher levels.
  [self.tagManager.logger setLogLevel:kTAGLoggerLogLevelVerbose];

  /*
   * Opens a container.
   *
   * @param containerId The ID of the container to load.
   * @param tagManager The TAGManager instance for getting the container.
   * @param openType The choice of how to open the container.
   * @param timeout The timeout period (default is 2.0 seconds).
   * @param notifier The notifier to inform on container load events.
   */
  [TAGContainerOpener openContainerWithId:@"GTM-XXXX"   // Update with your Container ID.
                               tagManager:self.tagManager
                                 openType:kTAGOpenTypePreferFresh
                                  timeout:nil
                                 notifier:self];

  // Method calls that don't need the container.

  return YES;
}

// TAGContainerOpenerNotifier callback.
- (void)containerAvailable:(TAGContainer *)container {
  // Note that containerAvailable may be called on any thread, so you may need to dispatch back to
  // your main thread.
  dispatch_async(dispatch_get_main_queue(), ^{
    self.container = container;
  });
}

// The rest of your app delegate implementation.

4. الحصول على قيم التهيئة من الحاوية

بعد فتح الحاوية، يمكن استرداد قيم الإعدادات باستخدام طرق <type>ForKey: التالية:

// Retrieving a configuration value from a Tag Manager Container.

MyAppDelegate *appDelegate = (MyAppDelegate *)[[UIApplication sharedApplication] delegate];
TAGContainer *container = appDelegate.container;

// Get the configuration value by key.
NSString *title = [container stringForKey:@"title_string"];

ستعرض الطلبات المقدَّمة باستخدام مفتاح غير متوفّر قيمة تلقائية مناسبة للنوع المطلوب:

// Empty keys will return a default value depending on the type requested.

// Key does not exist. An empty string is returned.
NSString subtitle = [container stringForKey:@"Non-existent-key"];
[subtitle isEqualToString:@""]; // Evaluates to true.

5. دفع القيم إلى DataLayer

DataLayer هي خريطة تتيح إمكانية توفير معلومات وقت التشغيل عن تطبيقك، مثل أحداث اللمس أو طرق عرض الشاشة، في وحدات الماكرو وعلامات "إدارة العلامات من Google" في حاوية.

على سبيل المثال، من خلال دفع معلومات عن مرّات مشاهدة الصفحة في التطبيق إلى خريطة DataLayer، يمكنك إعداد العلامات في واجهة الويب في أداة "إدارة العلامات من Google" لتنشيط وحدات بكسل الإحالات الناجحة وتتبُّع المكالمات استجابةً لمشاهدات الصفحة في التطبيق بدون الحاجة إلى ترميزها بشكل ثابت في تطبيقك.

يتم إرسال الأحداث إلى DataLayer باستخدام السمة push:.

//
//  ViewController.m
//  Pushing an openScreen event with a screen name into the data layer.
//

#import "MyAppDelegate.h"
#import "TAGDataLayer.h"
#import "ViewController.h"

@implementation ViewController

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];

    // The container should have already been opened, otherwise events pushed to
    // the data layer will not fire tags in that container.
    TAGDataLayer *dataLayer = [TAGManager instance].dataLayer;

    [dataLayer push:@{@"event": @"openScreen", @"screenName": @"Home Screen"}];
}

// Rest of the ViewController implementation

@end

في واجهة الويب، يمكنك الآن إنشاء علامات (مثل علامات "إحصاءات Google") لتنشيطها لكل مشاهدة شاشة من خلال إنشاء هذه القاعدة: يساوي "openscreen". ولتمرير اسم الشاشة إلى إحدى هذه العلامات، أنشِئ وحدة ماكرو لطبقة البيانات تشير إلى المفتاح screenName في طبقة البيانات. يمكنك أيضًا إنشاء علامة (مثل بكسل إحالة ناجحة في "إعلانات Google") لتنشيطها فقط لمشاهدات شاشة معيّنة، وذلك عن طريق إنشاء قاعدة يكون فيها يساوي "openScreen" && يساوي "ConfirmationScreen".

6. معاينة حاوية ونشرها

وستتوافق قيم الماكرو دائمًا مع الإصدار المنشور الحالي. قبل نشر أحدث إصدار من الحاوية، يمكنك معاينة حاوية المسودة.

لمعاينة إحدى الحاويات، أنشئ عنوان URL للمعاينة في واجهة ويب "إدارة العلامات من Google" عن طريق اختيار إصدار الحاوية التي تريد معاينتها، ثم اختيار Preview. احتفظ بعنوان URL للمعاينة هذا حيث ستحتاج إليه في خطوات لاحقة.

تتوفّر معاينة عناوين URL في نافذة المعاينة على واجهة الويب لأداة &quot;إدارة العلامات من Google&quot;.
الشكل 1: الحصول على عنوان URL للمعاينة من واجهة الويب لأداة "إدارة العلامات من Google".

لتفعيل معاينات الحاوية، يجب إضافة رمز إلى ملف تنفيذ تفويض التطبيق وتحديد مخطط عنوان URL لمعاينة أداة "إدارة العلامات من Google" في قائمة مواقع مشروعك.

أولاً، أضِف مقتطفات الرمز الغامقة التالية إلى ملف تفويض تطبيقك:

@implementation MyAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  self.tagManager = [TAGManager instance];
  
  // Add the code in bold below to preview a Google Tag Manager container.
  // IMPORTANT: This code must be called before the container is opened.
  NSURL *url = [launchOptions valueForKey:UIApplicationLaunchOptionsURLKey];
  if (url != nil) {
    [self.tagManager previewWithUrl:url];
  }
  
  id<TAGContainerFuture> future =
      [TAGContainerOpener openContainerWithId:@"GTM-XXXX"    // Placeholder Container ID.
                                   tagManager:self.tagManager
                                     openType:kTAGOpenTypePreferNonDefault
                                      timeout:nil];

  // The rest of your method implementation.

  self.container = [future get];

  return YES;
}


// Add the code in bold below preview a Google Tag Manager container.
- (BOOL)application:(UIApplication *)application
            openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication
         annotation:(id)annotation {

  if ([self.tagManager previewWithUrl:url]) {
    return YES;
  }

  // Code to handle other urls.
  return NO;
}

بعد ذلك، سجِّل معرِّف عنوان URL التالي ومخطط عنوان URL ضمن مفتاح أنواع عناوين URL في ملف قائمة خصائص تطبيقك:

URL identifier: your.package_name
URL scheme: tagmanager.c.your.package.name
سجِّل مخطط عنوان URL لمعاينة أداة &quot;إدارة العلامات من Google&quot; في ملف قائمة الخصائص لتطبيقك.
الشكل 3: إضافة مخطط عنوان URL لمعاينة أداة "إدارة العلامات من Google" إلى ملف قائمة خصائص تطبيقك.

افتح الرابط على محاكي أو جهاز مادي لمعاينة حاوية المسودة في تطبيقك.

عندما تكون مستعدًا لإتاحة مسودة قيم الإعدادات لتطبيقك، عليك نشر الحاوية.

إعداد متقدم

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

الخيارات المتقدمة لفتح الحاويات

توفّر حزمة تطوير البرامج (SDK) لأداة "إدارة العلامات من Google" عدّة طرق لفتح الحاويات التي يمكن أن تمنحك قدرًا أكبر من التحكّم في عملية التحميل:

openContainerById:callback:

openContainerById:callback: هو أدنى مستوى والأكثر مرونة من واجهة برمجة التطبيقات لفتح الحاوية. ويتم عرضها في الحال بحاوية افتراضية، كما تُحمّل بشكل غير متزامن حاوية من القرص أو الشبكة في حال عدم وجود حاوية محفوظة أو إذا لم تكن الحاوية المحفوظة جديدة (منذ أكثر من 12 ساعة).

@interface ContainerCallback : NSObject<TAGContainerCallback>

@end

@implementation ContainerCallback

/**
 * Called before the refresh is about to begin.
 *
 * @param container The container being refreshed.
 * @param refreshType The type of refresh which is starting.
 */
- (void)containerRefreshBegin:(TAGContainer *)container
                  refreshType:(TAGContainerCallbackRefreshType)refreshType {
  // Notify UI that container refresh is beginning.
}

/**
 * Called when a refresh has successfully completed for the given refresh type.
 *
 * @param container The container being refreshed.
 * @param refreshType The type of refresh which completed successfully.
 */
- (void)containerRefreshSuccess:(TAGContainer *)container
                    refreshType:(TAGContainerCallbackRefreshType)refreshType {
  // Notify UI that container is available.
}

/**
 * Called when a refresh has failed to complete for the given refresh type.
 *
 * @param container The container being refreshed.
 * @param failure The reason for the refresh failure.
 * @param refreshType The type of refresh which failed.
 */
- (void)containerRefreshFailure:(TAGContainer *)container
                        failure:(TAGContainerCallbackRefreshFailure)failure
                    refreshType:(TAGContainerCallbackRefreshType)refreshType {
  // Notify UI that container request has failed.
}
@end

خلال عملية التحميل، يُصدر openContainerById:callback: عدة استدعاءات في مراحل نشاط التحميل ليتمكّن الرمز البرمجي من رصد وقت بدء طلب التحميل وما إذا كان تعذُّر التحميل أو نجاحه وسبب ذلك وما إذا تم تحميل الحاوية من القرص أو الشبكة في نهاية المطاف.

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

تمرر openContainerById:callback: قيم enum التالية كوسيطات إلى استدعاءات الاتصال هذه:

RefreshType

القيمةالوصف
kTAGContainerCallbackRefreshTypeSaved يُحمِّل طلب إعادة التحميل حاوية محفوظة محليًا.
kTAGContainerCallbackRefreshTypeNetwork طلب إعادة التحميل يحمِّل حاوية عبر الشبكة.

RefreshFailure

القيمةالوصف
kTAGContainerCallbackRefreshFailureNoSavedContainer لا تتوفر أي حاوية محفوظة.
kTAGContainerCallbackRefreshFailureIoError منع خطأ في وحدات الإدخال والإخراج إعادة تحميل الحاوية.
kTAGContainerCallbackRefreshFailureNoNetwork لا يتوفر اتصال بالشبكة.
kTAGContainerCallbackRefreshFailureNetworkError حدث خطأ في الشبكة.
kTAGContainerCallbackRefreshFailureServerError حدث خطأ في الخادم.
kTAGContainerCallbackRefreshFailureUnknownError حدث خطأ يتعذّر تصنيفه.

طرق فتح الحاويات غير التلقائية والطازجة

يشمل TAGContainerOpener الترميز openContainerById:callback: ويوفّر طريقتين لفتح الحاويات، وهما: openContainerWithId:tagManager:openType:timeout:notifier: وopenContainerWithId:tagManager:openType:timeout:.

وتتطلّب كل طريقة من هذه الطرق تعدادًا يطلب إما حاوية غير تلقائية أو جديدة.

يُنصَح باستخدام kTAGOpenTypePreferNonDefault لمعظم التطبيقات ومحاولة عرض أول حاوية غير تلقائية متاحة خلال فترة مهلة معيّنة، سواء من القرص أو الشبكة، حتى إذا كان عمر هذه الحاوية أكبر من 12 ساعة. وإذا عرضت حاوية محفوظة قديمة، سيتم أيضًا تقديم طلب شبكة غير متزامن لحاوية جديدة. عند استخدام kTAGOpenTypePreferNonDefault، سيتم عرض حاوية تلقائية في حال عدم توفّر أي حاوية أخرى أو في حال تجاوز مدة المهلة.

تحاول الدالة kTAGOpenTypePreferFresh عرض حاوية جديدة من قرص أو شبكة خلال فترة المهلة المحددة. ويعرض حاوية محفوظة إذا كان اتصال الشبكة غير متاح و/أو تم تجاوز فترة المهلة.

لا يُنصح باستخدام kTAGOpenTypePreferFresh في الأماكن التي قد يؤثر فيها وقت أطول للطلب بشكل ملحوظ في تجربة المستخدم، مثل علامات واجهة المستخدم أو سلاسل العرض. ويمكنك أيضًا استخدام TAGContainer::refresh في أي وقت لفرض طلب حاوية الشبكة.

لا تؤدي كلتا الطريقتين الملائمتين إلى الحظر. تعرض openContainerWithId:tagManager:openType:timeout: كائن TAGContainerFuture، حيث تعرض طريقة get الخاصة به الرمز TAGContainer بمجرد تحميله (ولكنه سيتم حظره حتى ذلك الحين). تستخدم الطريقة openContainerWithId:tagManager:openType:timeout:notifier: استدعاء واحد، يتم استدعاؤه عند توفر الحاوية. وتم تحديد مهلة تلقائية تبلغ 2.0 ثانية في كلتا الطريقتين.

تقييم وحدات الماكرو في وقت التشغيل باستخدام القواعد

يمكن للحاويات تقييم القيم في وقت التشغيل باستخدام القواعد. قد تستند القواعد إلى معايير مثل لغة الجهاز أو النظام الأساسي أو أي قيمة ماكرو أخرى. على سبيل المثال، يمكن استخدام القواعد لاختيار سلسلة معروضة مترجَمة استنادًا إلى لغة الجهاز في وقت التشغيل. يمكن تهيئة ذلك باستخدام القاعدة التالية:

يتم استخدام قاعدة لاختيار سلاسل العرض بناءً على لغة الجهاز في وقت التشغيل: اللغة تساوي es. تستخدم هذه القاعدة وحدة ماكرو اللغة المحددة مسبقًا ورمز لغة ISO 639-1 مؤلفًا من حرفين.
الشكل 1:إضافة قاعدة لتفعيل ماكرو جمع القيم فقط للأجهزة التي تم إعدادها لاستخدام اللغة الإسبانية.

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

تجدر الإشارة إلى أنّه إذا كانت الحاوية التلقائية تحتاج إلى قواعد، يجب استخدام ملف حاوية ثنائي كحاوية تلقائية.

تعرَّف على مزيد من المعلومات عن ضبط القواعد (مركز المساعدة).

ملفات الحاوية التلقائية الثنائية

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

يمكن تنزيل ملفات الحاويات الثنائية من واجهة ويب "إدارة العلامات من Google"، ويجب إضافتها إلى حزمة التطبيق الرئيسية باتباع اصطلاح التسمية هذا: GTM-XXXX، حيث يمثل اسم الملف معرّف الحاوية.

في الحالات التي يتوفّر فيها ملف قائمة الخصائص و/أو ملف JSON بالإضافة إلى ملف حاوية ثنائي، ستستخدِم حزمة تطوير البرامج (SDK) ملف الحاوية الثنائي كحاوية تلقائية.

استخدام وحدات ماكرو استدعاء الدوال

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

لضبط ماكرو لاستدعاء الدالة:

  1. حدِّد وحدة ماكرو استدعاء الدالة في واجهة الويب لأداة "إدارة العلامات من Google". يمكن ضبط الوسيطات اختياريًا كأزواج من المفتاح/القيمة.
  2. تحديد معالج ينفِّذ بروتوكول TAGFunctionCallMacroHandler: 
    // MyFunctionCallMacroHandler.h
#import "TAGContainer.h"

// The function name field of the macro, as defined in the Google Tag Manager
// web interface.
extern NSString *const kMyMacroFunctionName;

@interface MyFunctionCallMacroHandler : NSObject<TAGFunctionCallMacroHandler>

@end


// MyFunctionCallMacroHandler.m
#import "MyFunctionCallMacroHandler.h"

// Corresponds to the function name field in the Google Tag Manager interface.
NSString *const kMyMacroFunctionName = @"myConfiguredFunctionName";

@implementation MacroHandler

- (id)valueForMacro:(NSString *)functionName parameters:(NSDictionary *)parameters {

  if ([functionName isEqualToString:kMyMacroFunctionName]) {
    // Process and return the calculated value of this macro accordingly.
    return macro_value;
  }
  return nil;
}

@end
  3. سجِّل المعالج باستخدام TAGContainer::registerCallFunctionHandler:forMax: واسم الدالة المحدّد في واجهة أداة "إدارة العلامات من Google":
    4. //
// MyAppDelegate.h
//
#import <UIKit/UIKit.h>

@interface MyAppDelegate : UIResponder <UIApplicationDelegate>

@end


//
// MyAppDelegate.m
//
#import "MyAppDelegate.h"
#import "MyFunctionCallMacroHandler.h"
#import "TAGContainer.h"
#import "TAGContainerOpener.h"
#import "TAGManager.h"

@implementation MyAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  // Open the container.
  id<TAGContainerFuture> future =
      [TAGContainerOpener openContainerWithId:@"GTM-XXXX"    // Placeholder Container ID.
                                   tagManager:[TAGManager instance]
                                     openType:kTAGOpenTypePreferNonDefault
                                      timeout:nil];

  // Method calls that don't need the container.

  self.container = [future get];

  // Register a function call macro handler using the macro name defined
  // in the Google Tag Manager web interface.
  [self.container registerFunctionCallMacroHandler:[[MyFunctionCallMacroHandler alloc] init]
                                          forMacro:kMyMacroFunctionName];
}

@end

استخدام علامات استدعاء الدوالّ

تتيح علامات الاستدعاء للدالة إمكانية تنفيذ الوظائف المسجّلة مسبقًا عندما يتم إرسال حدث إلى طبقة البيانات ويتم تقييم قواعد العلامات إلى true.

لضبط علامة استدعاء الدالة:

  1. حدِّد علامة استدعاء الدالة في واجهة الويب لأداة "إدارة العلامات من Google". يمكن ضبط الوسيطات اختياريًا كأزواج من المفتاح/القيمة.
  2. تنفيذ بروتوكول TAGFunctionCallTagHandler: 
    //
// MyFunctionCallTagHandler.h
//

#import "TAGContainer.h"

extern NSString *const kMyTagFunctionName;

@interface MyFunctionCallTagHandler : NSObject<TAGFunctionCallTagHandler>

@end


//
// MyFunctionCallTagHandler.m
//

// Corresponds to the function name field in the Google Tag Manager interface.
NSString *const kMyTagFunctionName = @"myConfiguredFunctionName";

@implementation MyFunctionCallTagHandler

/**
 * This method will be called when any custom tag's rule(s) evaluate to true and
 * should check the functionName and process accordingly.
 *
 * @param functionName corresponds to the function name field, not tag
 *     name field, defined in the Google Tag Manager web interface.
 * @param parameters An optional map of parameters as defined in the Google
 *     Tag Manager web interface.
 */
- (void)execute:(NSString *)functionName parameters:(NSDictionary *)parameters {

  if ([functionName isEqualToString:kMyTagFunctionName]) {
    // Process accordingly.
  }
}
@end
  3. سجِّل معالِج علامة استدعاء الدالة باستخدام اسم العلامة الذي تم ضبطه في واجهة الويب لأداة "إدارة العلامات من Google":
    4. //
// MyAppDelegate.h
//
#import <UIKit/UIKit.h>

@interface MyAppDelegate : UIResponder <UIApplicationDelegate>

@end


//
// MyAppDelegate.m
//
#import "MyAppDelegate.h"
#import "MyFunctionCallTagHandler.h"
#import "TAGContainer.h"
#import "TAGContainerOpener.h"
#import "TAGManager.h"

@implementation MyAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  // Open the container.
  id<TAGContainerFuture> future =
      [TAGContainerOpener openContainerWithId:@"GTM-XXXX"    // Placeholder Container ID.
                                   tagManager:[TAGManager instance]
                                     openType:kTAGOpenTypePreferNonDefault
                                      timeout:nil];

  // Method calls that don't need the container.

  self.container = [future get];

  // Register a function call tag handler using the function name of the tag as
  // defined in the Google Tag Manager web interface.
  [self.container registerFunctionCallTagHandler:[[MyFunctionCallTagHandler alloc] init]
                                          forTag:kMyTagFunctionName];
}
@end

تعيين فترة إعادة تحميل مخصصة

ستحاول حزمة تطوير البرامج (SDK) لأداة "إدارة العلامات من Google" استرداد حاوية جديدة إذا تجاوز عمر الحاوية الحالي 12 ساعة. لضبط فترة إعادة تحميل حاوية مخصّصة، استخدِم NSTimer، كما في المثال التالي:

- (void)refreshContainer:(NSTimer *)timer {
  [self.container refresh];
}

self.refreshTimer = [NSTimer scheduledTimerWithTimeInterval:<refresh_interval>
                                                     target:self
                                                   selector:@selector(refreshContainer:)
                                                   userInfo:nil
                                                    repeats:YES];

تصحيح الأخطاء باستخدام المُسجّل

تطبع حزمة تطوير البرامج (SDK) لأداة "إدارة العلامات من Google" الأخطاء والتحذيرات إلى السجلات تلقائيًا. قد يكون تفعيل المزيد من التسجيل المطوَّل مفيدًا لتصحيح الأخطاء وقد يكون ممكنًا من خلال تنفيذ Logger الخاص بك، كما في هذا المثال:

// MyAppDelegate.h
// This example assumes this file is using ARC.
// This Logger class will print out not just errors and warnings (as the default
// logger does), but also info, debug, and verbose messages.
@interface MyLogger: NSObject<TAGLogger>
@end

@implementation MyLogger
- (void)error:(NSString *)message {
  NSLog(@"Error: %@", message);
}

- (void)warning:(NSString *)message {
  NSLog(@"Warning: %@", message);
}

- (void)info:(NSString *)message {
  NSLog(@"Info: %@", message);
}

- (void)debug:(NSString *)message {
  NSLog(@"Debug: %@", message);
}

- (void)verbose:(NSString *)message {
  NSLog(@"Verbose: %@", message);
}
@end

// MyAppDelegate.m
// This example assumes this file is using ARC.
@implementation MyAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  self.tagManager = [TAGManager instance];
  
  self.tagManager.logger = [[MyLogger alloc] init];
  
  // Rest of Tag Manager and method implementation.
  return YES;
}
// Rest of app delegate implementation.
@end

أو يمكنك ضبط LogLevel للمسجِّل الحالي باستخدام TagManager::logger::setLogLevel، كما في هذا المثال: 

// Change the LogLevel to INFO to enable logging at INFO and higher levels.
self.tagManager = [TAGManager instance];
[self.tagManager.logger setLogLevel:kTAGLoggerLogLevelInfo];