حاشیه نویسی، پارامترهای وفاداری و تنظیمات را تعریف کنید

این سند نحوه تنظیم حاشیه نویسی، پارامترهای وفاداری و تنظیمات را در پروژه خود شرح می دهد.

حاشیه نویسی و پارامترهای وفاداری

حاشیه نویسی اطلاعات متنی در مورد آنچه که بازی شما در هنگام ثبت تیک انجام می دهد را ارائه می دهد. پارامترهای Fidelity منعکس کننده عملکرد و تنظیمات گرافیکی بازی شما هستند. شما اینها را با استفاده از بافرهای پروتکل تعریف می‌کنید، که قالب‌های بی‌طرفانه، ساختار یافته و مبادله داده Google هستند. برای اطلاعات بیشتر در مورد استفاده از بافرهای پروتکل در بازی خود، درباره بافرهای پروتکل را ببینید.

حاشیه نویسی و پارامترهای وفاداری ممکن برای بازی شما در فایلی به نام dev_tuningfork.proto تعریف شده است که در فهرست assets/tuningfork پروژه شما قرار دارد. نمونه زیر از برنامه آزمایشی است:

syntax = "proto3";

package com.google.tuningfork;

enum InstrumentKey {
  CPU = 0;
  GPU = 1;
  SWAPPY_WAIT = 2;
  SWAPPY_SWAP = 3;
  CHOREOGRAPHER = 4;
}

enum Level {
  // 0 is not a valid value
  LEVEL_INVALID = 0;
  LEVEL_1 = 1;
  LEVEL_2 = 2;
  LEVEL_3 = 3;
};

message Annotation {
  Level level = 1;
}

message FidelityParams {
  int32 num_spheres = 1;
  float tesselation_percent = 2;
}

به موارد زیر توجه کنید:

• بسته باید com.google.tuningfork باشد.
• نام پیام باید دقیقاً Annotation و FidelityParams باشد.
• شما می توانید فقط enums تعریف شده در این فایل به عنوان بخشی از حاشیه نویسی استفاده کنید.
• شما فقط می توانید enums ، int32s یا floats در فیلدهای FidelityParams استفاده کنید.
• ابزار اعتبارسنجی این قراردادها را اجرا می کند.

تنظیمات

پیام Settings توسط tuningfork.proto تعریف شده است. نمونه کامل را در فایل زیر ببینید:

gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/tuningfork_settings.txt

شما باید تنظیمات بازی خود را در فایلی به نام tuningfork_settings.txt که در فهرست assets/tuningfork پروژه شما قرار دارد، تعریف کنید. فقط باید فیلدهای زیر را مشخص کنید:

• aggregation_strategy : پیامی حاوی موارد زیر:

  • method : TIME_BASED برای آپلود هر n میلی ثانیه یا TICK_BASED برای آپلود هر n تیک.
  • intervalms_or_count : n برای فیلد method .
  • max_instrumentation_keys : تعداد کلیدهای ابزار دقیق برای استفاده. اگر از کتابخانه Android Frame Pacing استفاده می کنید، روی 4 تنظیم کنید.
  • annotation_enum_size : یک فیلد اختیاری است زیرا اندازه در هنگام راه اندازی از توصیفگر محاسبه می شود.

• api_key : کلید API پروژه Cloud برنامه شما که برای اعتبارسنجی درخواست‌ها به نقطه پایانی استفاده می‌شود. برای تولید این کلید، به فعال کردن API مراجعه کنید. اگر خطاهای اتصال را در logcat مشاهده کردید، بررسی کنید که کلید API درست باشد.

• default_fidelity_parameters_filename : مجموعه پارامترهای وفاداری مورد استفاده در مقداردهی اولیه (در صورتی که training_fidelity_params در کد خود تنظیم کنید، اختیاری است).

• level_annotation_index : (اختیاری) ایندکس در قسمت های حاشیه نویسی شماره سطح شما.

در زیر نمونه ای از نمایش متن است:

aggregation_strategy: {method: TIME_BASED, intervalms_or_count: 10000,
  max_instrumentation_keys: 5, annotation_enum_size: [3,4]}
api_key: "API-KEY-FROM-GOOGLE-CLOUD-CONSOLE"
default_fidelity_parameters_filename: "dev_tuningfork_fidelityparams_3.bin"
level_annotation_index: 1

تنظیم حاشیه نویسی

شما باید به صورت دستی حاشیه نویسی را در طول بازی خود تنظیم کنید. می‌توانید نمونه‌ای از آن را در برنامه آزمایشی ببینید، زیرا به طور خودکار در تمام سطوح بازی می‌چرخد. برای اطلاعات بیشتر، تابع SetAnnotations() را در insightsdemo.cpp ببینید.

در این مورد، حاشیه نویسی فقط شماره سطح را مشخص می کند.

message Annotation {
  Level level = 1;
}

سطوح کیفیت را تعریف کنید

از سطوح کیفیت برای حاشیه نویسی جلسات استفاده کنید تا بتوانید تعیین کنید که آیا دستگاه ها در سطح کیفی بسیار بالا (در نتیجه عملکرد پایین تر) یا خیلی پایین (که منجر به کاهش وفاداری غیر ضروری می شود) کار می کنند.

شما باید حداقل یک و ترجیحاً چندین سطح کیفی برای بازی خود تعریف کنید. سطح کیفیت مربوط به نمونه ای از پیام FidelityParams شماست. این سطوح باید به ترتیب وفاداری فزاینده با فرمت نام فایل زیر داده شوند:

dev_tuningfork_fidelityparams_i.txt

که در آن i شاخصی است که از 1 شروع می شود و حداکثر مقدار آن 15 است. این فایل ها باید در فهرست assets/tuningfork پروژه شما قرار داشته باشند. پروژه نمونه نمونه ای از این ساختار را در پوشه gamesdk/samples/tuningfork/insightsdemo/app/src/main/assets/tuningfork/ نشان می دهد.

درباره بافرهای پروتکل

کتابخانه Tuning Fork از فرمت بافر پروتکل گوگل برای تنظیمات، حاشیه نویسی و پارامترهای وفاداری استفاده می کند. این یک پروتکل به خوبی تعریف شده و چند زبانه برای داده های ساختار یافته و قابل توسعه است. برای اطلاعات بیشتر، به مستندات Protocol Buffers مراجعه کنید.

Proto2 در مقابل proto3

نسخه فرمت بافر پروتکل در خط اول فایل تنظیم شده است:

syntax="proto2";

Proto2 و proto3 دو نسخه رایج از بافرهای پروتکل هستند. هر دو از یک فرمت سیم استفاده می کنند اما فایل های تعریف سازگار نیستند. تفاوت های اصلی بین این دو نسخه شامل موارد زیر است:

• کلمات کلیدی optional و required دیگر در proto3 مجاز نیستند.
• همه چیز به طور موثر در proto3 optional است.
• برنامه های افزودنی در proto3 پشتیبانی نمی شوند.

از proto3 در فایل های پروتو خود استفاده کنید زیرا این فایل ها را می توان در C# کامپایل کرد. Proto2 با مجموعه ویژگی های محدود مورد استفاده در کتابخانه Tuning Fork نیز کار می کند.

متن در مقابل نمایش های باینری

قالب سیم پروتوباف باینری به خوبی تعریف شده و در نسخه های مختلف پروتوباف پایدار است (کد تولید شده نیست). همچنین یک قالب متنی وجود دارد که نسخه کامل کتابخانه protobuf می تواند ایجاد و خوانده شود. این قالب به خوبی تعریف نشده است، اما برای مجموعه محدودی از ویژگی های کتابخانه Tuning Fork پایدار است. با استفاده از کامپایلر protoc می توانید بین فرمت های باینری و متنی تبدیل کنید. دستور زیر یک متن پروتوباف را به باینری تبدیل می کند:

protoc --encode com.google.tuningfork.Settings tuningfork.proto < tuningfork_settings.txt > tuningfork_settings.bin

شما باید فایل‌های باینری را به جای فایل‌های متنی در APK خود بگنجانید، زیرا کتابخانه کامل protobuf چندین مگابایت حجم دارد. وابستگی کتابخانه Tuning Fork به آن، اندازه بازی شما را به میزان مشابهی افزایش می دهد.

فول در مقابل Lite در مقابل نانو

علاوه بر کتابخانه کامل پروتوباف، نسخه‌ای Lite وجود دارد که با حذف برخی از ویژگی‌ها مانند بازتاب، FileDescriptors و جریان به و از قالب‌های متنی، ردپای کد را کاهش می‌دهد. این نسخه هنوز به چندین مگابایت کد اضافی نیاز دارد و بنابراین، کتابخانه Tuning Fork به صورت داخلی از کتابخانه nanopb استفاده می کند. کد منبع این کتابخانه در پروژه متن باز اندروید به صورت external/nanopb-c موجود است و بخشی از شاخه gamesdk است. اگر اندازه کد مشکل است از این کتابخانه در بازی خود استفاده کنید.

فایل‌های CMake در gamesdk/src/protobuf وجود دارند که می‌توانند به شما در ادغام هر سه نسخه از protobuf کمک کنند. نمونه ها از ترکیبی از هر دو nanopb و protobuf کامل استفاده می کنند.