شروع به کار با Metrix SDK برای Unity

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

پروژه نمونه: برای مشاهده یک پیاده‌سازی کامل و کاربری از Metrix SDK در Unity، می‌توانید پروژه نمونه ما را در GitHub  بررسی کنید.

۱. اضافه کردن پلاگین Metrix به پروژه Unity

برای شروع، باید پلاگین Metrix SDK را به پروژه Unity خود وارد کنید:

1. دانلود پلاگین: آخرین نسخه پلاگین Metrix Unity را از این لینک  دریافت کنید.
2. Import به پروژه: پس از دانلود، فایل MetrixSDK_UnityPlugin_vX.X.X.unitypackage را با دابل کلیک باز کنید یا آن را به پنجره Project در Unity بکشید تا پلاگین به پروژه شما Import شود.

۲. مدیریت وابستگی‌ها (Dependency Management)

پلاگین Metrix برای مدیریت وابستگی‌های خود، دو روش اصلی را پیشنهاد می‌کند: استفاده از External Dependency Manager for Unity (EDM4U) (روش خودکار و توصیه شده) یا افزودن وابستگی‌ها به صورت دستی در فایل Gradle پروژه (روش جایگزین).

۲.۱. روش توصیه شده: استفاده از External Dependency Manager (EDM4U)

این ابزار (که قبلاً با نام “Unity Jar Resolver” شناخته می‌شد) به طور خودکار کتابخانه‌های مورد نیاز را دانلود و به پروژه شما اضافه می‌کند.

• نصب EDM4U: اگر این ابزار را در پروژه خود ندارید، آخرین نسخه آن را از این لینک  دریافت کرده و آن را نیز در پروژه خود Import کنید.

۲.۲. روش جایگزین: افزودن دستی وابستگی‌ها به Gradle (فقط برای Android)

اگر ترجیح می‌دهید وابستگی‌ها را به صورت دستی مدیریت کنید و یا از EDM4U استفاده نمی‌کنید، می‌توانید dependencyهای Metrix را مستقیماً به فایل build.gradle پروژه Android خود اضافه کنید. این روش فقط برای بیلد Android کاربرد دارد.

1. پیکربندی build.gradle: مطمئن شوید که ریپازیتوری maven { url 'https://jitpack.io' } در فایل build.gradle سطح پروژه (Project-level build.gradle) در بخش allprojects { repositories { ... } } اضافه شده باشد.

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' } // Add this line
    }
}

2. افزودن Dependencies: وابستگی‌های زیر را به فایل build.gradle سطح ماژول (Module-level build.gradle، معمولاً app/build.gradle) در بخش dependencies { ... } اضافه کنید:

dependencies {
    implementation 'ir.metrix.analytics:metrix-unity:2.6.3'
    implementation 'ir.metrix.attribution:metrix-unity:2.6.3'
    implementation 'ir.metrix.notification:metrix-unity:2.6.3'
}

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

بسته به پلتفرم هدف (Android یا iOS) که برنامه خود را برای آن Build می‌کنید، مراحل راه‌اندازی اولیه کمی متفاوت خواهد بود.

۳.۱. راه‌اندازی برای اپلیکیشن‌های Android

1. حل وابستگی‌ها (Resolve Dependencies):

• اگر از EDM4U استفاده می‌کنید:
  • در Unity، به مسیر زیر بروید تا یک بار وابستگی‌های اندروید را Resolve کنید: Assets -> External Dependency Manager -> Android Resolver -> Resolve
• اگر وابستگی‌ها را دستی اضافه کرده‌اید:
  • نیازی به اجرای Android Resolver نیست. Unity و Gradle به طور خودکار وابستگی‌ها را هنگام Build پروژه مدیریت خواهند کرد.

2. پیکربندی AndroidManifest.xml: شناسه اپلیکیشن (APP_ID) و کلید API (API_KEY) Metrix خود را در فایل AndroidManifest.xml اپلیکیشن خود قرار دهید. این کلیدها برای شناسایی اپلیکیشن شما در Metrix ضروری هستند.

• مکان فایل: فایل AndroidManifest.xml معمولاً در مسیر Assets/Plugins/Android قرار دارد.

• فعال‌سازی Custom Manifest: اگر این فایل را مشاهده نمی‌کنید، ممکن است نیاز به فعال‌سازی “Custom Main Manifest” در تنظیمات Player Unity داشته باشید: Edit -> Project Settings... -> Player -> Android Setting (تب) -> Publishing Settings -> Custom Main Manifest را فعال کنید.

• افزودن کلیدها: خطوط زیر را درون تگ <application> در فایل AndroidManifest.xml اضافه کنید و مقادیر YOUR_APP_ID و YOUR_API_KEY را با کلیدهای خود جایگزین نمایید:

<manifest>
  ...
  <application>
    ...
    <meta-data
        android:name="ir.metrix.APPLICATION_ID"
        android:value="YOUR_APP_ID" />
 
    <meta-data
        android:name="ir.metrix.API_KEY"
        android:value="YOUR_API_KEY" />
 
  </application>
</manifest>

• YOUR_APP_ID: شناسه اپلیکیشن شما که از پنل Metrix دریافت می‌کنید.
• YOUR_API_KEY: کلید API شما که از پنل Metrix دریافت می‌کنید.

3. بررسی Permission برای Advertising ID: اطمینان حاصل کنید که پرمیشن com.google.android.gms.permission.AD_ID در مانیفست نهایی (merged manifest) پروژه شما وجود دارد. این پرمیشن برای جمع‌آوری Advertising ID دستگاه و عملکرد صحیح Attribution ضروری است:

<manifest>
    <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
  ...
</manifest>

۳.۲. راه‌اندازی برای اپلیکیشن‌های iOS

1. مقداردهی اولیه Metrix: در ابتدای اجرای برنامه خود (مثلاً در متد Awake یا Start یک MonoBehaviour که در صحنه اول بازی شما قرار دارد)، متد Initialize کتابخانه Metrix را فراخوانی کنید. این کار Metrix SDK را راه‌اندازی می‌کند.

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

using MetrixSDK;
using UnityEngine;
 
public class MetrixInitializer : MonoBehaviour
{
    void Awake()
    {
        Metrix.Initialize("YOUR_APP_ID"); // Replace YOUR_APP_ID with your actual App ID from Metrix dashboard
    }
}

2. مدیریت وابستگی‌ها با CocoaPods: کتابخانه Metrix از CocoaPods برای مدیریت وابستگی‌های خود در پروژه‌های iOS استفاده می‌کند. پس از Export کردن پروژه Unity خود به عنوان یک پروژه Xcode:

• در ترمینال (Terminal)، به مسیر پوشه پروژه Xcode (فولدر <your-iOS-project-directory>) بروید.

• دستور نصب پاد (pod install) را اجرا نمایید:

cd <your-iOS-project-directory>
pod install

این دستور تمام وابستگی‌های لازم را برای پروژه iOS شما نصب می‌کند.

۴. افزایش امنیت کتابخانه با SDK Signature (مخصوص Android)

شما می‌توانید با فعال‌سازی قابلیت SDK Signature در پنل Metrix، امنیت ارتباط و انتقال اطلاعات را افزایش داده و از سلامت آمار اپلیکیشن خود اطمینان بیشتری حاصل کنید. این قابلیت به متریکس اجازه می‌دهد تا صحت داده‌های ارسالی از سمت اپلیکیشن شما را تأیید کند.

پس از فعال‌سازی SDK Signature در پنل Metrix خود، شناسه مربوط به signature را از ستون Encoded دریافت نمایید. سپس، این شناسه را به شکل زیر در کد C# Unity خود قرار دهید (قبل از فراخوانی Metrix.Initialize یا بلافاصله پس از آن):

Metrix.setSignature("YOUR_SIGNATURE_FROM_METRIX_DASHBOARD");

توجه: این قابلیت در حال حاضر فقط برای پلتفرم Android در دسترس است.