SDK iOS

• تنظیمات اولیه در پروژه
  • پیاده‌سازی
  • افزودن SDK به پروژه
  • افزودن فریم‌ورک‌های iOS
  • یکپارچه سازی SDK در برنامه خود
  • راه اندازی اولیه
• ویژگی‌های اضافه
• رویداد سفارشی
• ساختن رویداد درآمدی
• ردگیری جریان صفحات
• شناسه‌های دستگاه
  • شناسه تبلیغاتی
  • شناسه متریکس
• ردگیرهای پیش‌نصب
  • دریافت اطلاعات کمپین
  • شناسه نشست متریکس

پروژه نمونه پیاده‌سازی متریکس در زبان Objective-C و Swift را می‌توانید مرور بفرمایید.

تنظیمات اولیه در پروژه

پیاده‌سازی

مراحل استفاده از SDK متریکس داخل پروژه iOS شما به شکل زیر است.

افزودن SDK به پروژه

اگر از CocoaPods استفاده می‌کنید، می‌توانید خط زیر را به Podfile خود اضافه کنید:

pod 'MetrixSdk', '>= 1.2.2', '< 2.0'

همچنین شما می‌توانید SDK متریکس را به عنوان یک framework به پروژه خود اضافه کنید.

از اینجا دانلود نماید.

از iOS 8 اپل فریم‌ورکهای پویا (dynamic frameworks یا embedded frameworks) را معرفی کرده است. اگر برنامه‌ شما iOSهای با نسخه 8 یا بالاتر را هدف‌گذاری کرده است، می‌توانید از فریم‌ورک پویای متریکس استفاده کنید.

افزودن فریم‌ورک‌های iOS

• پروژه خود را در قسمت Project Navigator انتخاب کنید.
• در قسمت سمت چپ target مورد نظر را انتخاب کنید.
• در تب Build Phases گروه Link Binary with Libraries را باز کنید.
• در پایین این بخش دکمه + رو انتخاب کنید.
• فرم‌ورک‌های AdSupport.framework و iAd.framework و CoreTelephony.framework را انتخاب کنید.
• وضعیت فریم‌ورکها را به Optional تغییر دهید.

یکپارچه سازی SDK در برنامه خود

باید از عبارت زیر برای import استفاده کنید.

#import <MetrixSdk/Metrix.h>

راه اندازی اولیه

در Project Navigatorُ فایل منبع application delegate خود را انتخاب کنید. عبارت import مناسب را در بالای فایل وارد کنید و سپس متد زیر را در متدهای didFinishLaunching یا didFinishLaunchingWithOptions فراخوانی کنید.

#import "Metrix.h"
// or #import <Metrix/Metrix.h>
// or #import <MetrixSdk/Metrix.h>

// ...

NSString *yourAppId = @"{YourAppId}";
NSString *environment = MXEnvironmentSandbox;
MXConfig *metrixConfig = [MXConfig configWithAppId:yourAppId
                                            environment:environment];

[Metrix appDidLaunch:metrixConfig];

نکته: راه‌ اندازی SDK به این شکل بسیار مهم است. در غیر این صورت ممکن است باعث مشکلات مختلف شود.

مقدار {YourAppId} را با مقدار Metrix App Id خود جایگزین کنید.

بسته به این که برنامه خود را برای تست یا محصول نهایی خروجی میگیرید، باید مقدار environment را یکی از موارد زیر قرار دهید:

NSString *environment = MXEnvironmentSandbox;
NSString *environment = MXEnvironmentProduction;

ویژگی‌های اضافه

بعد از پیاده‌سازی SDK می‌توانید از ویژگی‌های زیر استفاده کنید.

رویداد سفارشی

با استفاده از این تابع می‌توانید یک رویداد سفارشی بسازید. برای این کار شما در ابتدا باید در داشبورد متریکس از قسمت مدیریت رخدادها، رخداد موردنظر خود را ثبت کنید و نامک (slug) آن را بعنوان نام رخداد در sdk استفاده کنید. ابتدا باید یک رویداد سفارشی بسازید

MXCustomEvent *event = [MXCustomEvent newEvent:@"mySlug" attributes:myAttributes metrics:myMetrics];
[Metrix trackCustomEvent:event];

برای یک رویداد سفارشی میتوانید به تعداد دلخواه attribute و metric خاص سناریو خود بسازید، به عنوان مثال فرض کنید در یک برنامه خرید آنلاین می‌خواهید یک رویداد سفارشی بسازید:

NSMutableDictionary *myAttributes = [[NSMutableDictionary alloc] init];
    myAttributes[@"first_name"] = @"Ali";
    myAttributes[@"last_name"] = @"Bagheri";
    myAttributes[@"manufacturer"] = @"Nike";
    myAttributes[@"product_name"] = @"shirt";
    myAttributes[@"type"] = @"sport";
    myAttributes[@"size"] = @"large";
NSMutableDictionary *myMetrics = [[NSMutableDictionary alloc] init];
    myMetrics[@"price"] = @(100000);
    myMetrics[@"purchase_time"] = current_time;

ساختن رویداد درآمدی

با استفاده از این تابع می‌توانید یک رویداد درآمدی بسازید. برای این کار شما در ابتدا باید در داشبورد متریکس از قسمت مدیریت رخدادها، رخداد موردنظر خود را ثبت کنید و نامک (slug) آن را بعنوان نام رخداد در sdk استفاده کنید.

این تابع را به صورت زیر می‌توانید صدا بزنید:

یک رویداد سفارشی که فقط یک نامک مشخص دارد و آن را از داشبورد متریکس میگیرد، بسازید:

#import <MetrixSdk/MXCurrency.h>

[Metrix trackRevenue:@"mySlug" withValue:@12000 currency:IRR orderId:@"myOrderId"];

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

دومین وروی تابع یک مقدار است که همان مقدار درآمد است.

سومین ورودی واحد پول این رخداد است.

ورودی چهارم که به صورت دلخواه است میتواند شماره سفارش شما باشد.

ردگیری جریان صفحات

شما میتوانید جریان حرکت کاربران خود در صفحات برنامه خود را با متریکس ردگیری کنید. برای این کار باید به هنگام ورود به هر صفحه (در viewWillAppear یا viewDidApear) متد زیر را فراخوانی کنید:

[Metrix trackScreen:@"HomePage"];

شناسه‌های دستگاه

SDK متریکس امکان دسترسی به برخی شناسه‌های دستگاه را فراهم می‌کند.

شناسه تبلیغاتی

برخی سرویسها (مثل Google Analytics) شناسه یکتایی برای هر دستگاه فراهم میکنند تا از گزارش چندباره اطلاعات اجتناب کنند.

برای به دست آوردن این شناسه کافی است متد زیر را فراخوانی کنید:

NSString *idfa = [Metrix idfa];

شناسه متریکس

برای هر دستگاهی که برنامه شما را نصب میکند، سرور متریکس یک شناسه یکتا (mxid) تولید میکند.

بنابراین پیش از راه اندازی اولیه و ثبت برنامه شما در سرورهای متریکس دسترسی به این شناسه ممکن نیست.

برای به دست آوردن این شناسه میتوانید به شکل زیر عمل کنید:

NSString *mxid = [Metrix mxid];

ردگیرهای پیش‌نصب

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

برای این کار app delegate برنامه خود را باز کرده و trackerToken را برای MXConfig خود قرار دهید:

MXConfig *metrixConfig = [MXConfig configWithAppId:yourAppId environment:environment];
[metrixConfig setTrackerToken:@"{TrackerToken}"];
[Metrix appDidLaunch:metrixConfig];

بعد از اجرای برنامه باید لاگی به این شکل در XCode ببینید:

Tracker token: 'abc123'

دریافت اطلاعات کمپین

شما می‌توانید با تنظیم یک delegateاز تغییرات اطلاعات کمپین با خبر شوید. مراحل زیر را برای پیاده‌سازی delegate اختیاری مربوطه در AppDelegate خود طی نمایید:

1. در فایل AppDelegate.h:

    @interface AppDelegate : UIResponder <UIApplicationDelegate, MetrixDelegate>

1. تابع زیر را به AppDelegate.m اضافه کنید:

    - (void)metrixAttributionChanged:(MXAttribution *)attribution{
    }

1. تنظیم delegate در نمونه MXConfig خود:

    [metrixConfig setDelegate:self];

از آنجایی که delegate callback شما بر روی نمونه MXConfig تنظیم شده است، باید setDelegate قبل از [Metrix appDidLaunch:metrix Config] فراخوانی شود. در تابع delegate شما به پارامترهای کمپین دسترسی دارید:

• NSString trackerToken
• NSString acquisitionSource شبکه تبلیغاتی
• NSString acquisitionCampaign کمپین تبلیغاتی
• NSString acquisitionAdSet گروه تبلیغاتی
• NSString acquisitionAd نام تبلیغ
• NSString attributionStatus وضعیت کاربر در کمپین

مقدار attributionStatus شامل یکی از موارد زیر است:

• ATTRIBUTED
• NOT_ATTRIBUTED_YET
• ATTRIBUTION_NOT_NEEDED
• UNKNOWN

پس از این شما می‌توانید بدین شکل برای اطلاعات کمپین درخواست نمایید:

    [Metrix requestAttribution];

شناسه نشست متریکس

کتابخانه متریکس برای هر نشست یک شناسه منحصر به فرد تولید می‌کند. شما می‌توانید با تنظیم یک delegateاز شناسه نشست متریکس با خبر شوید. مراحل زیر را برای پیاده‌سازی delegate اختیاری مربوطه در AppDelegate خود طی نمایید:

1. در فایل AppDelegate.h:

	@interface AppDelegate : UIResponder <UIApplicationDelegate, MetrixDelegate>

1. تابع زیر را به AppDelegate.m اضافه کنید:

	- (void)metrixSessionIdChanged:(NSString *)sessionId{
	}

1. تنظیم delegate در نمونه MXConfig خود:

    [metrixConfig setDelegate:self];

از آنجایی که delegate callback شما بر روی نمونه MXConfig تنظیم شده است، باید setDelegate قبل از [Metrix appDidLaunch:metrix Config] فراخوانی شود.