راهنمای شروع برای هدف-C

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

مقدمه

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

این برای مدیریت هرگونه مقادیر پیکربندی یا پرچم‌هایی در برنامه شما که ممکن است در آینده نیاز به تغییر داشته باشند، مفید است، از جمله:

  • تنظیمات مختلف رابط کاربری و رشته‌های نمایشی
  • اندازه‌ها، مکان‌ها یا انواع تبلیغاتی که در برنامه شما ارائه می‌شوند
  • تنظیمات بازی

مقادیر پیکربندی همچنین می‌توانند در زمان اجرا با استفاده از قوانین ارزیابی شوند و پیکربندی‌های پویا مانند موارد زیر را امکان‌پذیر سازند:

  • استفاده از اندازه صفحه نمایش برای تعیین اندازه بنر تبلیغاتی
  • استفاده از زبان و مکان برای پیکربندی عناصر رابط کاربری

Google TagManager همچنین امکان پیاده‌سازی پویای تگ‌ها و پیکسل‌های ردیابی را در برنامه‌ها فراهم می‌کند. توسعه‌دهندگان می‌توانند رویدادهای مهم را در یک لایه داده قرار دهند و بعداً تصمیم بگیرند که کدام تگ‌ها یا پیکسل‌های ردیابی باید فعال شوند. TagManager از تگ‌های زیر پشتیبانی می‌کند:

  • تجزیه و تحلیل اپلیکیشن موبایل گوگل
  • برچسب فراخوانی تابع سفارشی

قبل از شروع

قبل از استفاده از این راهنمای شروع، به موارد زیر نیاز دارید:

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

شروع به کار

این بخش، توسعه‌دهندگان را در جریان گردش کار معمول Tag Manager راهنمایی می‌کند:

  1. کیت توسعه نرم‌افزار (SDK) گوگل تگ منیجر را به پروژه خود اضافه کنید.
  2. مقادیر پیش‌فرض کانتینر را تنظیم کنید
  3. کانتینر را باز کنید
  4. دریافت مقادیر پیکربندی از کانتینر
  5. ارسال رویدادها به لایه داده
  6. پیش‌نمایش و انتشار کانتینر

۱. افزودن SDK گوگل تگ منیجر به پروژه شما

قبل از استفاده از SDK گوگل تگ منیجر، باید libGoogleAnalyticsServices.a و فایل‌های هدر گوگل تگ منیجر (GTM) را از دایرکتوری Library بسته SDK به پروژه خود اضافه کنید.

در مرحله بعد، اگر کتابخانه‌های لینک‌شده‌ی زیر در برنامه‌ی هدف شما وجود ندارند، آن‌ها را به آن‌ها اضافه کنید:

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

اگر می‌خواهید برنامه شما از طریق ماکروهای SDK گوگل تگ منیجر به شناسه تبلیغ‌کنندگان (IDFA) و پرچم ردیابی ارائه شده توسط آن چارچوب دسترسی داشته باشد، باید این کتابخانه‌های اضافی را نیز پیوند دهید:

  • libAdIdAccess.a
  • AdSupport.framework

۲. افزودن یک فایل کانتینر پیش‌فرض به پروژه‌تان

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

برای دانلود و افزودن یک فایل باینری کانتینر پیش‌فرض به برنامه خود، این مراحل را دنبال کنید:

  1. وارد رابط وب گوگل تگ منیجر شوید.
  2. نسخه کانتینری که می‌خواهید دانلود کنید را انتخاب کنید.
  3. برای بازیابی فایل باینری کانتینر، روی دکمه دانلود کلیک کنید.
  4. فایل باینری را به دایرکتوری ریشه پروژه خود و پوشه "فایل‌های پشتیبان" در پروژه خود اضافه کنید.

نام فایل پیش‌فرض باید شناسه کانتینر (container ID) باشد (برای مثال GTM-1234 ). پس از دانلود فایل باینری، حتماً پسوند نسخه (version suffix) را از نام فایل حذف کنید تا از رعایت صحیح قرارداد نامگذاری اطمینان حاصل شود.

اگرچه استفاده از فایل باینری توصیه می‌شود، اما اگر کانتینر شما حاوی قوانین یا تگ‌ها نیست، می‌توانید به جای آن از یک لیست ویژگی یا فایل JSON استفاده کنید. این فایل باید در بسته اصلی قرار گیرد و از این قرارداد نامگذاری پیروی کند: <Container_ID>.<plist|json> . به عنوان مثال، اگر شناسه کانتینر شما GTM-1234 است، می‌توانید مقادیر پیش‌فرض کانتینر خود را در یک فایل لیست ویژگی با نام GTM-1234.plist مشخص کنید.

۳. باز کردن یک کانتینر

قبل از بازیابی مقادیر از یک کانتینر، برنامه شما باید کانتینر را باز کند. باز کردن یک کانتینر، آن را از دیسک (در صورت وجود) بارگذاری می‌کند، یا آن را از شبکه (در صورت نیاز) درخواست می‌کند.

ساده‌ترین راه برای باز کردن یک کانتینر در 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.

۴. دریافت مقادیر پیکربندی از کانتینر

پس از باز شدن کانتینر، می‌توان مقادیر پیکربندی را با استفاده از متدهای <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.

۵. ارسال مقادیر به لایه داده

لایه داده (DataLayer) نقشه‌ای است که امکان دسترسی به اطلاعات زمان اجرا در مورد برنامه شما، مانند رویدادهای لمسی یا نماهای صفحه نمایش را برای ماکروها و تگ‌های Tag Manager در یک کانتینر فراهم می‌کند.

برای مثال، با وارد کردن اطلاعات مربوط به نماهای صفحه نمایش به نقشه DataLayer، می‌توانید تگ‌هایی را در رابط وب Tag Manager تنظیم کنید تا پیکسل‌های تبدیل و فراخوانی‌های ردیابی را در پاسخ به آن نماهای صفحه نمایش، بدون نیاز به کدنویسی دقیق آنها در برنامه خود، فعال کنند.

رویدادها با استفاده از 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

در رابط وب، اکنون می‌توانید با ایجاد این قانون، تگ‌هایی (مانند تگ‌های گوگل آنالیتیکس) ایجاد کنید که برای هر نمای صفحه نمایش فعال شوند: برابر با "openScreen" است. برای ارسال نام صفحه نمایش به یکی از این تگ‌ها، یک ماکروی لایه داده ایجاد کنید که به کلید "screenName" در لایه داده اشاره می‌کند. همچنین می‌توانید با ایجاد قانونی که در آن برابر با "openScreen" و برابر با "ConfirmationScreen" باشد، یک تگ (مانند پیکسل تبدیل گوگل ادز) ایجاد کنید که فقط برای نماهای صفحه نمایش خاص فعال شود.

۶. پیش‌نمایش و انتشار یک کانتینر

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

برای پیش‌نمایش یک کانتینر، با انتخاب نسخه کانتینری که می‌خواهید پیش‌نمایش آن را ببینید و سپس انتخاب Preview ، یک URL پیش‌نمایش در رابط وب Google Tag Manager ایجاد کنید. این URL پیش‌نمایش را ذخیره کنید زیرا در مراحل بعدی به آن نیاز خواهید داشت.

پیش‌نمایش URLها در پنجره پیش‌نمایش رابط وب Tag Manager در دسترس است.
شکل ۱: دریافت پیش‌نمایش URL از رابط وب Tag Manager.

برای فعال کردن پیش‌نمایش کانتینرها، باید کدی را به فایل پیاده‌سازی نماینده برنامه خود اضافه کنید و طرح URL پیش‌نمایش Google Tag Manager را در لیست ویژگی‌های پروژه خود تعریف کنید.

ابتدا، قطعه کدهای پررنگ زیر را به فایل نماینده برنامه خود اضافه کنید:

@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 پیش‌نمایش مدیریت تگ را در فایل لیست ویژگی برنامه خود ثبت کنید.
شکل ۳: افزودن طرح پیش‌نمایش URL تگ منیجر به فایل فهرست ویژگی برنامه شما.

برای پیش‌نمایش کانتینر پیش‌نویس در برنامه خود، لینک را روی یک شبیه‌ساز یا دستگاه فیزیکی باز کنید.

وقتی آماده بودید که مقادیر پیکربندی پیش‌نویس خود را در دسترس برنامه‌تان قرار دهید، کانتینر را منتشر کنید .

پیکربندی پیشرفته

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

گزینه‌های پیشرفته برای باز کردن کانتینرها

کیت توسعه نرم‌افزار گوگل تگ منیجر (Google Tag Manager SDK) روش‌های مختلفی برای باز کردن کانتینرها ارائه می‌دهد که می‌توانند کنترل بیشتری بر فرآیند بارگذاری به شما بدهند:

openContainerById:callback:

openContainerById:callback: پایین‌ترین سطح و انعطاف‌پذیرترین API برای باز کردن یک کانتینر است. این API بلافاصله یک کانتینر پیش‌فرض را برمی‌گرداند و همچنین اگر کانتینر ذخیره‌شده‌ای وجود نداشته باشد، یا اگر کانتینر ذخیره‌شده تازه نباشد (بیش از ۱۲ ساعت از تاریخ آن گذشته باشد)، آن را به صورت غیرهمزمان از دیسک یا شبکه بارگذاری می‌کند.

@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: چندین فراخوانی چرخه عمر صادر می‌کند تا کد شما بتواند بفهمد که درخواست بارگذاری چه زمانی آغاز می‌شود، آیا با شکست مواجه می‌شود یا موفق می‌شود و چرا، و اینکه آیا کانتینر در نهایت از دیسک یا شبکه بارگذاری شده است یا خیر.

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

openContainerById:callback: مقادیر enum زیر را به عنوان آرگومان به این callbackها ارسال می‌کند:

نوع تازه‌سازی

ارزش توضیحات
kTAGContainerCallbackRefreshTypeSaved درخواست به‌روزرسانی در حال بارگذاری یک کانتینر ذخیره‌شده محلی است.
kTAGContainerCallbackRefreshTypeNetwork درخواست به‌روزرسانی در حال بارگذاری یک کانتینر از طریق شبکه است.

عدم موفقیت در تازه‌سازی

ارزش توضیحات
kTAGContainerCallbackRefreshFailureNoSavedContainer هیچ ظرف ذخیره شده‌ای در دسترس نیست.
kTAGContainerCallbackRefreshFailureIoError یک خطای ورودی/خروجی مانع از به‌روزرسانی کانتینر شد.
kTAGContainerCallbackRefreshFailureNoNetwork هیچ اتصال شبکه‌ای در دسترس نیست.
kTAGContainerCallbackRefreshFailureNetworkError خطایی در شبکه رخ داده است.
kTAGContainerCallbackRefreshFailureServerError خطایی در سرور رخ داده است.
kTAGContainerCallbackRefreshFailureUnknownError خطایی رخ داده است که نمی‌توان آن را دسته‌بندی کرد.

روش‌های باز کردن کانتینرهای غیر پیش‌فرض و کانتینرهای تازه

TAGContainerOpener شامل openContainerById:callback: و دو متد برای باز کردن کانتینرها ارائه می‌دهد: openContainerWithId:tagManager:openType:timeout:notifier: و openContainerWithId:tagManager:openType:timeout: .

هر یک از این متدها یک enumeration دریافت می‌کنند که یک container غیر پیش‌فرض یا fresh را درخواست می‌کند.

kTAGOpenTypePreferNonDefault برای اکثر برنامه‌ها توصیه می‌شود و تلاش می‌کند اولین کانتینر غیر پیش‌فرض موجود را در یک دوره زمانی مشخص، چه از دیسک و چه از شبکه، حتی اگر آن کانتینر بیش از ۱۲ ساعت قدمت داشته باشد، بازگرداند. اگر یک کانتینر ذخیره شده قدیمی را برگرداند، یک درخواست شبکه ناهمزمان برای یک کانتینر جدید نیز ارسال می‌کند. هنگام استفاده از kTAGOpenTypePreferNonDefault ، اگر هیچ کانتینر دیگری در دسترس نباشد یا اگر دوره زمانی از دست رفته باشد، یک کانتینر پیش‌فرض بازگردانده می‌شود.

kTAGOpenTypePreferFresh تلاش می‌کند تا یک کانتینر جدید را از دیسک یا شبکه در بازه زمانی مشخص شده بازگرداند. اگر اتصال شبکه در دسترس نباشد و/یا از بازه زمانی تعیین شده فراتر رود، یک کانتینر ذخیره شده را برمی‌گرداند.

استفاده از kTAGOpenTypePreferFresh در جاهایی که زمان درخواست طولانی‌تر ممکن است به طور قابل توجهی بر تجربه کاربر تأثیر بگذارد، مانند پرچم‌های رابط کاربری یا رشته‌های نمایش، توصیه نمی‌شود. همچنین می‌توانید در هر زمانی TAGContainer::refresh برای اعمال درخواست کانتینر شبکه استفاده کنید.

هر دوی این متدهای کمکی غیر مسدودکننده هستند. openContainerWithId:tagManager:openType:timeout: یک شیء TAGContainerFuture برمی‌گرداند که متد get آن به محض بارگذاری، یک TAGContainer را برمی‌گرداند (اما تا آن زمان مسدود خواهد بود). متد openContainerWithId:tagManager:openType:timeout:notifier: یک فراخوانی مجدد می‌گیرد که وقتی کانتینر در دسترس باشد، فراخوانی می‌شود. هر دو متد دارای دوره زمانی پیش‌فرض 2.0 ثانیه هستند.

ارزیابی ماکروها در زمان اجرا با استفاده از قوانین

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

یک قانون برای انتخاب رشته‌های نمایشی بر اساس زبان دستگاه در زمان اجرا استفاده می‌شود: زبان برابر است با es. این قانون از ماکروی زبان از پیش تعریف شده و یک کد زبان دو کاراکتری ISO 639-1 استفاده می‌کند.
شکل ۱: افزودن قانونی برای فعال کردن ماکروی جمع‌آوری مقادیر فقط برای دستگاه‌هایی که برای استفاده از زبان اسپانیایی پیکربندی شده‌اند.

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

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

درباره پیکربندی قوانین بیشتر بدانید (مرکز راهنما).

فایل‌های کانتینر پیش‌فرض دودویی

کانتینرهای پیش‌فرض که به قوانین نیاز دارند، باید به جای یک فایل فهرست ویژگی‌ها یا فایل JSON به عنوان کانتینر پیش‌فرض، از یک فایل کانتینر باینری استفاده کنند. کانتینرهای باینری از تعیین مقادیر ماکرو در زمان اجرا با قوانین Google Tag Manager پشتیبانی می‌کنند، در حالی که فایل‌های فهرست ویژگی‌ها یا JSON این قابلیت را ندارند.

فایل‌های کانتینر باینری را می‌توان از رابط وب گوگل تگ منیجر دانلود کرد و باید با پیروی از این قرارداد نامگذاری به بسته اصلی برنامه شما اضافه شوند: GTM-XXXX ، که در آن نام فایل نشان دهنده شناسه کانتینر شما است.

در مواردی که یک فایل لیست ویژگی و/یا فایل JSON و همچنین یک فایل کانتینر باینری وجود داشته باشد، SDK از فایل کانتینر باینری به عنوان کانتینر پیش‌فرض استفاده خواهد کرد.

استفاده از ماکروهای فراخوانی تابع

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

برای پیکربندی یک ماکروی فراخوانی تابع:

  1. ماکروی فراخوانی تابع را در رابط وب گوگل تگ منیجر تعریف کنید. آرگومان‌ها می‌توانند به صورت اختیاری به صورت جفت‌های کلید-مقدار پیکربندی شوند.
  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::registerFunctionCallMacroHandler:forMacro: و نام تابع مشخص شده در رابط Google Tag Manager، هندلر را ثبت کنید: 
    //
// 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. تگ فراخوانی تابع را در رابط وب گوگل تگ منیجر تعریف کنید. آرگومان‌ها می‌توانند به صورت اختیاری به صورت جفت‌های کلید-مقدار پیکربندی شوند.
  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 Tag Manager، کنترل‌کننده‌ی تگ فراخوانی تابع را ثبت کنید: 
    //
// 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 گوگل تگ منیجر سعی می‌کند یک کانتینر جدید را بازیابی کند. برای تنظیم دوره به‌روزرسانی کانتینر سفارشی، از NSTimer مانند مثال زیر استفاده کنید: 

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

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

اشکال زدایی با Logger

کیت توسعه نرم‌افزار گوگل تگ منیجر (Google Tag Manager SDK) به طور پیش‌فرض خطاها و هشدارها را در لاگ‌ها چاپ می‌کند. فعال کردن لاگ‌های طولانی‌تر می‌تواند برای اشکال‌زدایی مفید باشد و با پیاده‌سازی 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) مربوط به Logger موجود را با استفاده از 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];