اضافه‌کردن کتابخانه به پروژه

pod مربوط به کتابخانه متریکس را به صورت زیر به Podfile پروژه خود اضافه و دستور نصب را اجرا نمایید:

pod 'Metrix/native', '2.0.3'

در صورتی که از CocoaPods در پروژه خود استفاده نمی‌کنید، می‌توانید فایل مربوط به فریمورک کتابخانه را از اینجا دریافت و به پروژه خود اضافه نمایید.

راه‌اندازی کتابخانه در اپلیکیشن

از عبارت زیر جهت import متریکس استفاده نمایید:

Swift

import Metrix

Objective-C

@import Metrix;

در کلاس AppDelegate پروژه خود و در متد didFinishLaunchingWithOptions با فراخوانی متد زیر، کتابخانه متریکس را راه‌اندازی کنید:

Swift

MetrixClient.initialize(metrixAppId: "APP_ID")

Objective-C

[MetrixClient initializeWithMetrixAppId:@"APP_ID"];

APP_ID: کلید اپلیکیشن شما که از پنل متریکس دریافت می‌کنید.

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

امکانات و قابلیت‌ها

نشست (session)

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

شناسه نشست

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

Swift

MetrixClient.setSessionIdListener { (sessionId: String) in
    // your logic
}

Objective-C

[MetrixClient setSessionIdListener:^(NSString *sessionId) {
    // your logic
}];

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

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

Swift

MetrixClient.setSessionNumberListener { (sessionNum: Int) in
    // your logic
}

Objective-C

[MetrixClient setSessionNumberListener:^(NSInteger sessionNumber) {
    // your logic
}];

رویداد (event)

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

در کتابخانه متریکس دو نوع رویداد قابل تعریف است:

• سفارشی (custom): وابسته به منطق اپلیکیشن شما و تعاملی که کاربر با اپلیکیشن شما دارد می‌توانید رویدادهای سفارشی خود را در قالبی که در ادامه شرح داده خواهد شد بسازید و ارسال کنید.
• درآمدی (revenue): نوع خاصی از رویدادهای سفارشی قابل تعریف است که مربوط به میزان درآمد کسب شده در اپلیکیشن شما می‌باشد و دارای یک مقدار قابل اندازه‌گیری از جنس درآمد مالی است.

ساختن یک رویداد سفارشی

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

وقوع رویداد به دو صورت می‌تواند ثبت شود:

۱. ثبت رویداد تنها با استفاده از نامک آن که در پنل معرفی شده است:

Swift

MetrixClient.newEvent(slug: "event-slug")

Objective-C

[MetrixClient newEventWithSlug: @"event-slug"];

۲. ثبت رویداد به همراه تعداد دلخواه attribute مربوط به آن:

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

Swift

let myAttributes = [
            "first_name": "Mohammad",
            "last_name": "Bagheri",
            "manufacturer": "Nike",
            "product_name": "shirt",
            "type": "sport",
            "size": "large"]

MetrixClient.newEvent(slug: "jqgjh", attributes: myAttributes)

Objective-C

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";

[MetrixClient newEventWithSlug: @"jqgjh" attributes:myAttributes];

ورودی‌های متد newEvent در این حالت، بدین شرح هستند:

• ورودی اول: نامک رویداد مورد نظر شما که در پنل متریکس معرفی شده است.
• ورودی دوم: یک Dictionary که ویژگی‌های یک رویداد را مشخص می‌کند.

توجه: هر رویداد می‌تواند حداکثر ۵۰ attribute داشته باشد که طول key و value آن حداکثر ۵۱۲ بایت می‌باشد.

مشخص کردن Attribute‌های پیش‌فرض همه‌ی رویدادها

با استفاده از این تابع می‌توانید به تعداد دلخواه Attribute به همه‌ی رویدادهای خود اضافه کنید:

Swift

let attributes = ["manufacturer": "Nike"]
MetrixClient.addUserAttributes(userAttrs: attributes)

Objective-C

NSMutableDictionary *attributes = [[NSMutableDictionary alloc] init];
attributes[@"manufacturer"] = @"Nike";

[MetrixClient addUserAttributesWithUserAttrs: attributes];

توجه: هر رویداد می‌تواند حداکثر ۵۰ attribute داشته باشد که طول key و value آن حداکثر ۵۱۲ بایت می‌باشد.

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

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

Swift

MetrixClient.newRevenue(slug: "my_event_slug", revenue: 12000, currency: .IRR, orderId: "myOrderId")

Objective-C

[MetrixClient newRevenueWithSlug: @"my_event_slug" revenue: 12000 currency: RevenueCurrencyIRR orderId: @"myOrderId"];

ورودی‌های متد newRevenue بدین شرح هستند:

• ورودی اول: نامک رویداد مورد نظر شما که در پنل متریکس معرفی شده است.
• ورودی دوم: یک مقدار عددی است که همان میزان درآمد است.
• ورودی سوم: واحد پول مورد استفاده است و می‌تواند سه مقدار .IRR (پیش‌فرض) یا .USD و یا .EUR را داشته باشد.
• ورودی چهارم: این ورودی دلخواه است و شماره سفارش را تعیین می‌کند.

دریافت شناسه دستگاه‌های متریکس

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

Swift

MetrixClient.setUserIdListener { (userId: String) in
    // your logic
}

Objective-C

[MetrixClient setUserIdListener:^(NSString *userId) {
    // your logic
}];

نکته: شناسه متریکس زمانی در اختیار شما قرار می‌گیرید که دستگاه توسط سرویس متریکس شناسایی شده باشد.

امضاء کتابخانه

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

در صورتی که sdk signature را در پنل خود فعال کرده‌اید و به app secret ها دسترسی دارید نیاز است که متد زیر را فراخوانی کنید:

Swift

MetrixClient.setAppSecret(secretId: secretId, info1: info1, info2: info2, info3: info3, info4: info4)

Objective-C

[MetrixClient setAppSecretWithSecretId:secretId info1:info1 info2:info2 info3:info3 info4:info4];

توجه: این فراخوانی باید در متد didFinishLaunchingWithOptions در کلاس AppDelegate برنامه صورت گیرد.

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

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

Swift

MetrixClient.setOnAttributionChangedListener { (data: AttributionData) in
    print("Attribution status: \(data.attributionStatus.rawValue)")
    // TODO
}

Objective-C

[MetrixClient setOnAttributionChangedListener:^(AttributionData *data) {
    printf("AttributionStatus: %s", [[data attributionStatusRaw] UTF8String]);
    // TODO
}];

مدل AttributionData اطلاعات زیر را در اختیار شما قرار می‌دهد.

attributionData.acquisitionAd // نام تبلیغ
attributionData.acquisitionAdSet // گروه تبلیغاتی
attributionData.acquisitionCampaign // کمپین تبلیغاتی
attributionData.acquisitionSource // شبکه تبلیغاتی
attributionData.attributionStatus // وضعیت کاربر در کمپین را مشخص می‌کند

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

• ATTRIBUTED اتربیوت شده
• NOT_ATTRIBUTED_YET هنوز اتربیوت نشده
• ATTRIBUTION_NOT_NEEDED نیاز به اتربیوت ندارد
• UNKNOWN حالت ناشناخته

مشخص کردن tracker پیش‌فرض

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

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

Swift

MetrixClient.setDefaultTracker(trackerToken: "tracker-token")

Objective-C

[MetrixClient setDefaultTrackerWithTrackerToken: @"tracker-token"];

توجه: این فراخوانی باید در متد didFinishLaunchingWithOptions در کلاس AppDelegate برنامه صورت گیرد.

تفکیک نصب‌های organic بر‌اساس استور‌های مختلف

اگر شما می‌خواهید اپلیکیشن خود را در استور های مختلف مانند منتشر کنید، می‌توانید مشاهده کنید که کاربر از کدام استور ( مثلا اپ‌استور، سیبچه و... ) اپلیکیشن را نصب کرده و منبع نصب‌های ارگانیک خود را شناسایی کنید.

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

Swift

MetrixClient.setStore(storeName: "store name")

Objective-C

[MetrixClient setStoreWithStoreName:@"store name"];

توجه: این فراخوانی باید در متد didFinishLaunchingWithOptions در کلاس AppDelegate برنامه صورت گیرد.