אתחול הספרייה ואימות הפעולה

בדף הזה מוסבר איך לאתחל את הספרייה בקוד המשחק ולוודא שהיא מעלה נתונים ל-Google Play. למידע נוסף על פונקציות ספציפיות בספרייה, אפשר לעיין במסמכי העזרה.

הפעלת הספרייה

בשיטת אתחול בתחילת המשחק, מאתחלים את הספרייה על ידי יצירת מופע של AndroidPerformanceTuner וקריאה לשיטה Start():

using Google.Android.PerformanceTuner;
using UnityEngine;

public class SomeBehaviour : MonoBehaviour
{
    AndroidPerformanceTuner<FidelityParams, Annotation> tuner =
            new AndroidPerformanceTuner<FidelityParams, Annotation>();

    void Start()
    {
        ErrorCode startErrorCode = tuner.Start();
        Debug.Log("Android Performance Tuner started with code: " + startErrorCode);

        tuner.onReceiveUploadLog += request =>
        {
            Debug.Log("Telemetry uploaded with request name: " + request.name);
        };
    }
}

הקוד הזה מספיק כדי להפעיל את Android Performance Tuner ולבצע אינסטרומנטציה במשחק. הצהרות היומן מציינות מתי Android Performance Tuner התחיל לפעול ומתי נתוני הטלמטריה הועלו אל ממשקי ה-API של Google Play Console. בהמשך, תוכלו למצוא את ההצהרות האלה ביומן כדי לוודא שהתוסף פועל בצורה תקינה.

אתחול מאוחר (Vulkan בלבד)

אם המשחק שלכם מיועד ל-Vulkan ומשתמש ב-Android Frame Pacing, הכלי Android Performance Tuner צריך לבצע אתחול מאוחר:

IEnumerator Start()
{
    yield return new WaitForEndOfFrame();
    ErrorCode startErrorCode = tuner.Start();
    Debug.Log("Android Performance Tuner started with code: " + startErrorCode);

    tuner.onReceiveUploadLog += request =>
    {
        Debug.Log("Telemetry uploaded with request name: " + request.name);
    };
}

אימות המרווח בין העלאות של נתוני טלמטריה

ברירת המחדל של המרווח בין העלאות טלמטריה בהגדרות של התוסף היא 30 שניות. הזמן הזה מוגדר למרווח קצר כדי שיהיה קל יותר לאמת את ההעלאה התקינה של נתוני הטלמטריה. כשמשיקים את המשחק לגרסת הייצור, צריך להגדיר את הערך הזה למרווח גדול (לדוגמה, כל 10 דקות) כדי שהמשחק לא ישלח יותר מדי בקשות לממשקי ה-API. זה חשוב במיוחד למשתמשים שאין להם תוכנית נתונים לנייד שכוללת נתונים ללא הגבלה. מרווח גדול גם מונע שימוש יתר בסוללה של המכשיר.

כדי לוודא שהמרווח מוגדר ל-30 שניות:

  1. כדי לגשת להגדרות, בוחרים באפשרות Google > Android Performance Tuner.
  2. בוחרים בכרטיסייה הגדרות של הטמעה ולוחצים על שימוש בהגדרות מתקדמות.
  3. מוודאים שהשדה Intervals (minutes) (מרווחים (דקות)) מכיל את הערך 0.5.

הכרטיסייה הגדרות של כלי המדידה בפלאגין

אימות פעולה תקינה

אם אתם משתמשים ב-IL2CPP או בהסרת קוד, כדאי לעיין במאמר בנושא ניהול הסרת קוד.

בונים את המשחק ל-Android. בזמן שהמשחק מופעל במכשיר, פותחים מסוף במחשב ומפעילים את adb logcat:

adb logcat

בפלט של adb logcat, מחפשים את TuningFork (כי זה השם הפנימי של הספרייה):

02-03 16:55:45.103 10511 10536 I TuningFork: Got settings from tuningfork/tuningfork_settings.bin
02-03 16:55:45.103 10511 10536 I TuningFork: Using local file cache at /data/user/0/com.Unity3d.BoatAttackDay/cache/tuningfork
02-03 16:55:45.105 10511 10536 I TuningFork: OpenGL version 3.2
02-03 16:55:45.105 10511 10536 I TuningFork: TuningFork.GoogleEndpoint: OK
02-03 16:55:45.106 10511 10611 I TuningFork: Creating directory /data/user/0/com.Unity3d.BoatAttackDay/cache/tuningfork
02-03 16:55:45.106 10511 10536 I TuningFork: TuningFork Settings:

[...]

02-03 16:55:45.116 10511 10536 I Unity   : Tuningfork started with code: Ok
02-03 16:55:45.107 10511 10536 I TuningFork: TuningFork initialized
02-03 16:55:45.107 10511 10536 I UnityTuningfork: Swappy backend: 1
02-03 16:55:45.107 10511 10536 I TuningFork: Creating directory /data/user/0/com.Unity3d.BoatAttackDay/cache/tuningfork/V1
02-03 16:55:45.110 10511 10613 I TuningFork: OpenGL version 3.2
02-03 16:55:45.110 10511 10613 I TuningFork:Web: Connecting to: https://performanceparameters.googleapis.com/v1/applications/com.Unity3d.BoatAttackDay/apks/1:generateTuningParameters

אם עשיתם טעות בהגדרת הפלאגין, למשל שכחתם להגדיר את מפתח ה-API, תופיע שגיאה ביומני האתחול:

02-03 16:49:44.970  8815  8831 I TuningFork: Got settings from tuningfork/tuningfork_settings.bin
02-03 16:49:44.971  8815  8831 I TuningFork: Using local file cache at /data/user/0/com.Unity3d.BoatAttackDay/cache/tuningfork
02-03 16:49:44.972  8815  8831 I TuningFork: OpenGL version 3.2
02-03 16:49:44.972  8815  8831 W TuningFork.GE: The API key in Tuning Fork TFSettings is invalid
02-03 16:49:44.972  8815  8831 E TuningFork: TuningFork.GoogleEndpoint: FAILED
02-03 16:49:44.973  8815  8831 I Unity   : Tuningfork started with code: BadParameter

בודקים שהכלי Android Performance Tuner מעלה טלמטריה. אם מופיע TuningFork initialized ביומנים, צריך לחכות עוד קצת ולחפש יומנים שמציינים שהטֶלֶמֶטריה מועלית.

02-03 16:58:00.552 10511 10611 I TuningFork:Web: Connecting to: https://performanceparameters.googleapis.com/v1/applications/com.Unity3d.BoatAttackDay/apks/1:uploadTelemetry
02-03 16:58:00.898 10511 10611 I TuningFork:Web: Response code: 200
02-03 16:58:00.898 10511 10611 I TuningFork:Web: Response message: OK
02-03 16:58:00.899 10511 10611 I TuningFork.GE: UPLOAD request returned 200 {}

אפשר גם לחפש ביומנים את המחרוזת 'Connecting to:'. אחרי ההודעה הזו מופיע קוד התגובה, כמה שורות מתחת.

אם לא רואים יומני העלאה של טלמטריה, צריך לוודא שהגדרתם נכון את המרווח בין כל העלאה בהגדרות של Android Performance Tuner לערך קטן, כמו 30 שניות.

ניהול של הסרת קוד

Google.Protobuf.dll משתמש בהרהור. במהלך הסרת הקוד, יכול להיות שחלק מהקוד הנדרש יוסר. כדי למנוע את ההסרה הזו, התוסף מכיל קובץ link.xml עם מידע על הסמלים שצריך לשמור. אם אתם צריכים פונקציונליות מסוימת של protobuf שמשתמשת ברפלקציה והשבתתם את הסרת הקוד, אתם צריכים להוסיף את המידע הזה לקובץ link.xml כדי לשמור את הסמלים.

במסמכי Unity אפשר לקרוא מידע נוסף על הסרת קוד מנוהל.

אם אתם רוצים לשמור את כל הסמלים ב-protobuf, אתם צריכים להוסיף לפרויקט קובץ link.xml עם התוכן הבא:

<linker>
  <assembly fullname="Google.Protobuf" preserve="all"/>
</linker>

קומפילציה מראש (AOT)

הידור מראש נדרש עבור קצה העורפי IL2CPP וגרסאות Unity 2017 ו-2018 (אבל לא עבור גרסאות מאוחרות יותר של Unity).

יכול להיות שהקומפיילר AOT לא ייצור קוד לשיטות גנריות. צריך להוסיף את השיטה הבאה כדי לאלץ את הקומפיילר ליצור את הקוד המתאים שנדרש ל-protobuf:

using Google.Protobuf.Reflection;
using UnityEngine.Scripting;

...

// Don't call this method.
[Preserve]
void ExampleOfForceReflectionInitializationForProtobuf()
{
    FileDescriptor.ForceReflectionInitialization<Scene>();
    FileDescriptor.ForceReflectionInitialization<ShadowType>();
    FileDescriptor.ForceReflectionInitialization<LevelType>();
    ...
    // Add FileDescriptor.ForceReflectionInitialization<T> for each generated enum.
    // You can find the list of enums in DevTuningfork.cs -> enum section
    // or in the list of enums in Google -> Android Performance Tuner.
}

מידע נוסף על הגבלות על סקריפטים זמין במסמכי התיעוד של Unity.