کتابخانه متریکس برای Unity
- اضافه کردن پلاگین متریکس به پروژه
- راهاندازی کتابخانه در اپلیکیشن
- راهاندازی برای اپلیکیشن Android
- راهاندازی برای اپلیکیشن iOS
- امکانات و قابلیتها
- نشست (session)
- شناسه نشست
- شماره نشست جاری
- رویداد (event)
- ساختن یک رویداد سفارشی
- مشخص کردن Attributeهای پیشفرض همهی رویدادها
- ساختن رویداد درآمدی
- دریافت شناسه دستگاههای متریکس
- امضاء کتابخانه
- فعالسازی برای اپلیکیشن Android
- فعالسازی برای اپلیکیشن iOS
- شمارش پاک کردن اپلیکیشن Android
- دریافت اطلاعات کمپین
- Deep Linking در اپلیکیشن Android
- سناریو استاندارد
- سناریو deferred
- مشخص کردن tracker پیشفرض
- فعالسازی برای اپلیکیشن Android
- فعالسازی برای اپلیکیشن iOS
- تفکیک نصبهای organic براساس استورهای مختلف
- فعالسازی برای اپلیکیشن Android
- فعالسازی برای اپلیکیشن iOS
۱. پلاگین متریکس را از اینجا دریافت نمایید و در پروژه خود import کنید.
۲. مدیریت وابستگی
پلاگین متریکس از External Dependency Manager for Unity برای مدیریت وابستگیهای خود استفاده میکند.
در صورتی که این ابزار را در پروژه خود ندارید، آخرین نسخه آن را از اینجا دریافت نمایید و در پروژه خود import کنید.
بسته به build system هدف برنامه خود مراحل زیر را جهت فعالسازی انجام دهید:
۱. از مسیر زیر یکبار وابستگیها را resolve کنید:
Assets -> External Dependency Manager -> Android Resolver -> Resolve
۲. شناسه app id
متریکس را به صورت زیر در فایل AndroidManifest.xml
اپلیکیشن اضافه نمایید:
<manifest>
...
<application>
...
<!-- خطوط زیر را اضافه کنید و کلید اپلیکیشن خود را جایگزین نمایید -->
<meta-data
android:name="metrix_appId"
android:value="APP_ID" />
</application>
</manifest>
APP_ID
: کلید اپلیکیشن شما که از پنل متریکس دریافت میکنید.
فایل AndroidManifest.xml
در مسیر Assets/Plugins/Android
قرار دارد.
در صورتی که این فایل را مشاهده نمیکنید، از مسیر زیر اضافهشدن آن را به پروژه خود فعال کنید:
Edit -> Project Settings... -> Player -> Android Setting (Tab) -> Publishing Settings -> Custom Main Manifest
۱. در ابتدای برنامهی خود، مطابق قطعه کد زیر، با فراخوانی متد initialize
، کتابخانه متریکس را راهاندازی کنید:
Metrix.Initialize("APP_ID");
APP_ID
: کلید اپلیکیشن شما که از پنل متریکس دریافت میکنید.
۲. کتابخانه متریکس از CocoaPods برای اضافه کردن وابستگی خود استفاده میکند. پس از export پروژه iOS اپلیکیشن خود، در مسیر پروژه iOS، دستور نصب پاد را به صورت زیر اجرا نمایید:
cd <your-iOS-project-directory>
pod install
هر تعاملی که کاربر با یک اپلیکیشن دارد، در قالب یک نشست صورت میگیرد. کتابخانه متریکس اطلاعات مربوط به نشستهای مختلف کاربر در اپلیکیشن شما و بازه زمانی آنها را جمعآوری میکند و در اختیار شما میگذارد.
کتابخانه متریکس برای هر نشست یک شناسه منحصر به فرد تولید میکند که میتوانید این شناسه را دریافت نمایید. برای دریافت این شناسه متد زیر را فراخوانی کنید.
void MetrixSessionIdListener(string sessionId) {
// your logic
}
Metrix.SetSessionIdListener(MetrixSessionIdListener);
با استفاده از متد زیر میتوانید از شماره نشست جاری کاربر در تمام مدت استفاده خود از اپلیکیشن شما اطلاع پیدا کنید:
void MetrixSessionNumberListener(string sessionNumber) {
// your logic
}
Metrix.SetSessionNumberListener(MetrixSessionNumberListener);
هرگونه تعاملی که کاربر با اپلیکیشن شما دارد میتواند به عنوان یک رویداد در پنل و اپلیکیشن شما تعریف شود تا کتابخانه متریکس اطلاعات آماری مربوط به آن را در اختیار شما قرار دهد.
در کتابخانه متریکس دو نوع رویداد قابل تعریف است:
- سفارشی (custom): وابسته به منطق اپلیکیشن شما و تعاملی که کاربر با اپلیکیشن شما دارد میتوانید رویدادهای سفارشی خود را در قالبی که در ادامه شرح داده خواهد شد بسازید و ارسال کنید.
- درآمدی (revenue): نوع خاصی از رویدادهای سفارشی قابل تعریف است که مربوط به میزان درآمد کسب شده در اپلیکیشن شما میباشد و دارای یک مقدار قابل اندازهگیری از جنس درآمد مالی است.
برای ساخت یک رویداد سفارشی در ابتدا در پنل خود از قسمت مدیریت رویدادها، رویداد موردنظر خود را ثبت کنید و نامک (slug) آن را به عنوان نام رویداد در اپلیکیشن استفاده کنید.
وقوع رویداد به دو صورت میتواند ثبت شود:
۱. ثبت رویداد تنها با استفاده از نامک آن که در پنل معرفی شده است:
Metrix.NewEvent("my_event_slug");
۲. ثبت رویداد به همراه تعداد دلخواه attribute مربوط به آن:
به عنوان مثال فرض کنید در یک برنامه خرید آنلاین میخواهید یک رویداد سفارشی بسازید:
var attributes = new Dictionary<string, string>();
attributes.Add("first_name", "Ali");
attributes.Add("last_name", "Bagheri");
attributes.Add("manufacturer", "Nike");
attributes.Add("product_name", "shirt");
attributes.Add("type", "sport");
attributes.Add("size", "large");
Metrix.NewEvent("purchase_event_slug", attributes);
ورودیهای متد NewEvent در این حالت، بدین شرح هستند:
- ورودی اول: نامک رویداد مورد نظر شما که در پنل متریکس معرفی شده است.
- ورودی دوم: یک
Dictionary<string, string>
که ویژگیهای یک رویداد را مشخص میکند.
با استفاده از این تابع میتوانید به تعداد دلخواه Attribute
به همهی رویدادهای خود اضافه کنید:
var attributes = new Dictionary<string, string>();
attributes.Add("manufacturer", "Nike");
Metrix.AddUserAttributes(attributes);
توجه: هر رویداد میتواند حداکثر ۵۰ attribute داشته باشد که طول key و value آن حداکثر ۵۱۲ بایت میباشد.
با استفاده از این تابع میتوانید یک رویداد درآمدی بسازید. برای این کار در ابتدا در پنل خود از قسمت مدیریت رویدادها، رویداد موردنظر خود را ثبت کنید و نامک (slug) آن را به عنوان نام رویداد در اپلیکیشن استفاده کنید.
Metrix.NewRevenue("my_event_slug", 12000, 0, "myOrderId");
ورودیهای متد NewRevenue بدین شرح هستند:
- ورودی اول: نامک رویداد مورد نظر شما که در پنل متریکس معرفی شده است.
- ورودی دوم: یک مقدار عددی است که همان میزان درآمد است.
- ورودی سوم: واحد پول مورد استفاده را تعیین میکند و میتواند سه مقدار 0 (ریال) (پیشفرض) یا 1 (دلار) و یا 3 (یورو) را داشته باشد.
- ورودی چهارم: این ورودی دلخواه است و شناسه سفارش را تعیین میکند.
برای هر دستگاهی که اپلیکیشن شما را نصب کند، متریکس یک شناسه منحصر به فرد تولید میکند که شما میتوانید این شناسه را به محض شناسایی دریافت نمایید. برای دسترسی به این شناسه از متد استفاده کنید:
void MetrixUserIdListener(string metrixUserId) {
// your logic
}
Metrix.SetUserIdListener(MetrixUserIdListener);
نکته: شناسه متریکس زمانی در اختیار شما قرار میگیرید که دستگاه توسط سرویس متریکس شناسایی شده باشد.
شما میتوانید با فعالسازی قابلیت sdk signature در پنل خود و دریافت شناسه مخصوص خود، امنیت ارتباط و انتقال اطلاعات را افزایش داده و از سلامت آمار اپلیکیشن خود اطمینان بیشتری حاصل کنید.
پس از فعالسازی
sdk signature
در پنل خود، از ستون
Encoded
شناسه مربوط به
signature
را دریافت و به شکل زیر در فایل
AndroidManifest.xml
برنامه خود قرار دهید:
<manifest>
...
<application>
...
<!-- خطوط زیر را اضافه کنید و شناسه را جایگزین نمایید -->
<meta-data
android:name="metrix_signature"
android:value="YOUR_SIGNATURE" />
</application>
</manifest>
در صورتی که sdk signature را در پنل خود فعال کردهاید و به app secret ها دسترسی دارید نیاز است که متد زیر را فراخوانی کنید:
Metrix.SetAppSecret(secretId, info1, info2, info3, info4);
متریکس برای شمارش پاک شدن اپلیکشن شما از ارسال silent push استفاده میکند.
شما باید برای استفاده از این ابزار از Firebase Cloud Messaging (FCM) استفاده نمایید.
مراحل زیر را دنبال نمایید:
- وارد کردن
server key
و
sender id
پروژه فایربیس در پنل متریکس
در پنل متریکس به تنظیمات اپلیکیشن خود رفته و سربرگ Push Configuration را انتخاب کنید.
در این صفحه
server key
و
sender id
پروژه فایربیس خود را در فیلد های مربوطه وارد کنید و با کلیک بر روی دکمه
save
مقادیر را ذخیره کنید.
این مقادیر را میتوانید از کنسول فایربیس خود در بخش project settings در سربرگ Cload Messaging دریافت نمایید.
- فعالسازی شمارش حذف
پس از وارد کردن
server key
و
sender id
در پنل متریکس، با روشن کردن toggle مربوطه، شمارش حذف را فعال کنید.
- ارسال توکن پوش در اپلیکیشن
پس از پیادهسازی FCM در اپلیکیشن خود، به هنگام دریافت توکن پوشنوتیفیکیشن، با فراخوانی متد زیر، این توکن را برای متریکس ارسال نمایید:
Metrix.SetPushToken(token);
با استفاده از متد زیر، میتوانید اطلاعات کمپین تبلیغاتی که در ترکر خود در پنل قرار دادهاید را دریافت کنید.
void MetrixAttributionChangedListener(MetrixAttribution metrixAttribution) {
// your logic
}
Metrix.SetOnAttributionChangedListener(MetrixAttributionChangedListener);
مدل MetrixAttribution
اطلاعات زیر را در اختیار شما قرار می دهد.
metrixAttribution.acquisitionAd // نام تبلیغ
metrixAttribution.acquisitionAdSet // گروه تبلیغاتی
metrixAttribution.acquisitionCampaign // کمپین تبلیغاتی
metrixAttribution.acquisitionSource // شبکه تبلیغاتی
metrixAttribution.attributionStatus // وضعیت کاربر در کمپین را مشخص میکند
مقدار AttributionStatus
شامل یکی از موارد زیر است:
ATTRIBUTED
اتربیوت شدهNOT_ATTRIBUTED_YET
هنوز اتربیوت نشدهATTRIBUTION_NOT_NEEDED
نیاز به اتربیوت نداردUNKNOWN
حالت ناشناخته
اگر شما از ترکر هایی که دیپلینک در آنها فعال است استفاده کنید، میتوانید اطلاعات url دیپلینک و محتوای آن را دریافت کنید. دستگاه بر اساس نصب بودن اپلیکیشن (سناریو استاندارد) یا نصب نبودن اپلیکیشن (سناریو deferred) واکنش نشان میدهد. در صورت نصب بودن اپلیکیشن شما اطلاعات دیپلینک به اپلیکیشن شما ارسال میشود.
پلتفرم اندروید به صورت اتوماتیک سناریو deferred را پشتیبانی نمیکند. در این صورت متریکس سناریو مخصوص به خود را دارد تا بتواند اطلاعات دیپلینک را به اپلیکیشن ارسال کند.
برای پیاده سازی سناریو استاندارد میتوانید مستندات یونیتی را در اینجا مرور کنید.
این سناریو زمانی رخ میدهد که کاربر روی دیپلینک کلیک میکند ولی اپلیکیشن شما را در زمان کلیک بر روی دستگاه خود نصب ندارد. در این حالت کاربر پس از کلیک، به Google Play هدایت میشود تا اپلیکیشن شما را نصب کند. با نصب اپلیکیشن، در اولین اجرا، اطلاعات دیپلینک به اپلیکیشن داده میشود.
اگر شما قصد دارید که سناریو deferred را کنترل کنید میتوانید از کالبک زیر استفاده نمایید:
void DeferredDeeplinkListener(string deeplink) {
// your logic
}
Metrix.SetShouldLaunchDeeplink(true);
Metrix.SetOnDeeplinkResponseListener(DeeplinkCallback);
بعد از این که متریکس اطلاعات دیپلینک را از سرور خود دریافت کرد محتوای آن را به کالبک بالا پاس میدهد. اگر متد SetShouldLaunchDeeplink
با مقدار true
فراخوانی شده باشد، متریکس به صورت اتوماتیک سناریو استاندارد را اجرا میکند و در غیر این صورت، متریکس فقط اطلاعات را در این کالبک قرار میدهد تا شما بر اساس آن اکشن مورد نظر خود را انجام دهید.
توجه: سناریو deffered تنها در صورت نصب اپلیکیشن از طریق Google Play Store قابل اجرا میباشد.
شما میتوانید برای کاربرانی که نصب آنها از یک کلیک ناشی نمیشود ترکر داشته باشید، به این منظور باید شناسه مربوط به ترکر خود را که در پنل تعریف کردهاید در اپلیکیشن قرار دهید.
کاربرد این قابلیت برای زمانی است که قصد انتشار مستقیم فایل APK برنامه خود را دارید و میخواهید آمار نصبهای برنامه از طریق این انتشار را در متریکس به تفکیک داشته باشید.
توجه: تحت هیچ شرایطی اپلیکیشن خود را با ترکر پیشفرض روی استور منتشر نکنید. در این صورت همه نصبهای ارگانیک شما نیز در متریکس روی ترکر مذکور شمرده میشود.
شناسه ترکر را به شکل زیر در فایل
AndroidManifest.xml
برنامه خود قرار دهید:
<manifest>
...
<application>
...
<!-- خطوط زیر را اضافه کنید و شناسه را جایگزین نمایید -->
<meta-data
android:name="metrix_trackerToken"
android:value="TOKEN" />
</application>
</manifest>
متد زیر را فراخوانی کنید:
Metrix.SetDefaultTracker(trackerToken);
اگر شما میخواهید اپلیکیشن خود را در استور های مختلف مانند کافه بازار، گوگل پلی و … منتشر کنید، میتوانید مشاهده کنید که کاربر از کدام استور ( مثلا کافه بازار، گوگل پلی، مایکت، اول مارکت و وبسایت ... ) اپلیکیشن را نصب کرده و منبع نصبهای ارگانیک خود را شناسایی کنید.
برای این منظور، نیاز است که برای اپلیکیشن خود جهت انتشار در استورهای مختلف، بیلدهای جداگانه بسازید و در هر بیلد نام استور مربوط را تنظیم نمایید.
نام استور را به شکل زیر در فایل
AndroidManifest.xml
برنامه خود قرار دهید:
<manifest>
...
<application>
...
<!-- خطوط زیر را اضافه کنید و نام استور را جایگزین نمایید -->
<meta-data
android:name="metrix_storeName"
android:value="STORE_NAME" />
</application>
</manifest>
متد زیر را فراخوانی کنید:
Metrix.SetStore("store name");