مرجع صدور مجوز

کلاس ها و رابط های LVL

جدول 1 همه فایل‌های منبع موجود در کتابخانه تأیید مجوز (LVL) را که از طریق Android SDK در دسترس هستند فهرست می‌کند. همه فایل ها بخشی از بسته com.android.vending.licensing هستند.

جدول 1. خلاصه کلاس ها و رابط های کتابخانه LVL.

دسته بندی	نام	توضیحات
بررسی مجوز و نتیجه	LicenseChecker	کلاسی که برای شروع بررسی مجوز، نمونه سازی می کنید (یا زیر کلاس).
	LicenseCheckerCallback	رابطی که برای رسیدگی به نتیجه بررسی مجوز پیاده سازی می کنید.
سیاست	سیاست	رابطی که بر اساس پاسخ مجوز برای تعیین اجازه دسترسی به برنامه کاربردی پیاده سازی می کنید.
	سیاست مدیریت سرور	اجرای Policy پیش فرض از تنظیمات ارائه شده توسط سرور صدور مجوز برای مدیریت ذخیره سازی محلی داده های مجوز، اعتبار مجوز، امتحان مجدد استفاده می کند.
	سیاست سختگیرانه	اجرای Policy جایگزین صدور مجوز را فقط بر اساس پاسخ مجوز مستقیم از سرور اعمال می کند. بدون حافظه پنهان یا درخواست امتحان مجدد.
مبهم سازی داده ها (اختیاری)	مبهم کننده	رابطی که در صورت استفاده از یک Policy (مانند ServerManagedPolicy) که داده های پاسخ مجوز را در یک فروشگاه دائمی ذخیره می کند، پیاده سازی می کنید. از یک الگوریتم مبهم سازی برای رمزگذاری و رمزگشایی داده های نوشته شده یا خوانده شده استفاده می کند.
	AESObfuscator	اجرای پیش‌فرض Obfuscator که از الگوریتم رمزگذاری/رمزگشایی AES برای مبهم کردن/از بین بردن داده‌ها استفاده می‌کند.
محدودیت دستگاه (اختیاری)	DeviceLimiter	رابطی که اگر می‌خواهید استفاده از یک برنامه را به یک دستگاه خاص محدود کنید، پیاده‌سازی می‌کنید. از LicenseValidator تماس گرفته شده است. پیاده‌سازی DeviceLimiter برای اکثر برنامه‌ها توصیه نمی‌شود، زیرا به یک سرور پشتیبان نیاز دارد و ممکن است باعث شود کاربر دسترسی به برنامه‌های دارای مجوز را از دست بدهد، مگر اینکه با دقت طراحی شده باشد.
	NullDeviceLimiter	اجرای پیش‌فرض DeviceLimiter که بدون عملیات است (اجازه دسترسی به همه دستگاه‌ها).
هسته کتابخانه، بدون نیاز به ادغام	ResponseData	کلاسی که دارای فیلدهای پاسخ مجوز است.
	License Validator	کلاسی که پاسخ دریافتی از سرور صدور مجوز را رمزگشایی و تأیید می کند.
	ValidationException	کلاسی که خطاهایی را نشان می دهد که هنگام تأیید صحت داده های مدیریت شده توسط Obfuscator رخ می دهد.
	PreferenceObfuscator	کلاس Utility که داده های مبهم را در فروشگاه SharedPreferences سیستم می نویسد/ می خواند.
	ILicensing Service	رابط IPC یک طرفه که از طریق آن درخواست بررسی مجوز به مشتری Google Play ارسال می شود.
	ILicenseResultListener	اجرای یک طرفه تماس IPC که در آن برنامه یک پاسخ ناهمزمان از سرور مجوز دریافت می کند.

پاسخ سرور

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

جدول 2. خلاصه فیلدهای پاسخ مجوز که توسط سرور Google Play بازگردانده شده است.

میدان	توضیحات
responseCode	کد پاسخ بازگردانده شده توسط سرور مجوز. کدهای پاسخ در کدهای پاسخ سرور مشخص شده اند.
signedData	الحاق رشته ای که داده های بازگردانده شده توسط سرور صدور مجوز را نگه می دارد، به شرح زیر: responseCode|nonce|packageName|versionCode|userId|timestamp:extras . responseCode : کد پاسخی که توسط سرور صدور مجوز بازگردانده می شود. nonce : بدون شناسه درخواست. packageName : نام بسته برنامه برای بررسی مجوز. versionCode : کد نسخه برنامه برای بررسی مجوز. userId : یک شناسه منحصر به فرد برای کاربر در هر برنامه، که در آن همان کاربر یک شناسه متفاوت برای یک برنامه دیگر دریافت می کند. timestamp : تعداد میلی ثانیه از دوره 01-01-1970 00:00:00 UTC تا درخواست. extras : اطلاعات اضافی برای کمک به مدیریت مجوز برنامه. فیلدهای اضافی در قسمت های اضافی پاسخ سرور مشخص شده اند.
signature	امضای signedData با استفاده از یک کلید ویژه برنامه.

کدهای پاسخ سرور

جدول 3 تمام کدهای پاسخ مجوز پشتیبانی شده توسط سرور مجوز را فهرست می کند. به طور کلی، یک برنامه کاربردی باید همه این کدهای پاسخ را مدیریت کند. به‌طور پیش‌فرض، کلاس LicenseValidator در LVL، تمام مدیریت لازم این کدهای پاسخ را برای شما فراهم می‌کند.

جدول 3. خلاصه کدهای پاسخی که توسط سرور Google Play در پاسخ مجوز بازگردانده شده است.

کد پاسخ	نمایش مقدار صحیح	توضیحات	امضا کرد؟	موارد اضافی	نظرات
LICENSED	0	برنامه برای کاربر مجوز دارد. کاربر برنامه را خریداری کرده یا مجاز به دانلود و نصب نسخه آلفا یا بتا برنامه است.	بله	VT ، GT ، GR	اجازه دسترسی با توجه به محدودیت های Policy .
LICENSED_OLD_KEY	2	مجوز برنامه برای کاربر است، اما نسخه به روز شده برنامه موجود است که با کلید دیگری امضا شده است.	بله	VT ، GT ، GR ، UT	به صورت اختیاری با توجه به محدودیت های Policy اجازه دسترسی را بدهید. می تواند نشان دهد که جفت کلید استفاده شده توسط نسخه برنامه نصب شده نامعتبر یا در خطر است. این برنامه می‌تواند در صورت نیاز اجازه دسترسی دهد یا به کاربر اطلاع دهد که ارتقا در دسترس است و استفاده بیشتر را تا زمان ارتقا محدود کند.
NOT_LICENSED	1	برنامه برای کاربر مجوز ندارد.	خیر		اجازه دسترسی ندهید.
ERROR_CONTACTING_SERVER	257	خطای محلی - برنامه Google Play احتمالاً به دلیل مشکلات در دسترس بودن شبکه نتوانست به سرور مجوز دسترسی پیدا کند.	خیر		بررسی مجوز را با توجه به محدودیت‌های Policy مجدد امتحان کنید.
ERROR_SERVER_FAILURE	4	خطای سرور - سرور نمی تواند جفت کلید برنامه را برای صدور مجوز بارگیری کند.	خیر		بررسی مجوز را با توجه به محدودیت‌های Policy مجدد امتحان کنید.
ERROR_INVALID_PACKAGE_NAME	258	خطای محلی - برنامه برای بسته ای که روی دستگاه نصب نشده است، درخواست بررسی مجوز کرد.	خیر		بررسی مجوز را دوباره امتحان نکنید. معمولاً ناشی از یک خطای توسعه است.
ERROR_NON_MATCHING_UID	259	خطای محلی - برنامه برای بسته‌ای که UID آن (بسته، جفت شناسه کاربر) با برنامه درخواست‌کننده مطابقت ندارد، درخواست بررسی مجوز کرد.	خیر		بررسی مجوز را دوباره امتحان نکنید. معمولاً ناشی از یک خطای توسعه است.
ERROR_NOT_MARKET_MANAGED	3	خطای سرور - برنامه (نام بسته) توسط Google Play شناسایی نشد.	خیر		بررسی مجوز را دوباره امتحان نکنید. می تواند نشان دهد که برنامه از طریق Google Play منتشر نشده است یا خطای توسعه در اجرای مجوز وجود دارد.

توجه: همانطور که در راه‌اندازی محیط تست مستند شده است، کد پاسخ را می‌توان به صورت دستی برای توسعه‌دهنده برنامه و هر کاربر آزمایشی ثبت‌شده از طریق کنسول Google Play لغو کرد.

توجه: قبلاً می‌توانستید یک برنامه را با آپلود یک نسخه «پیش‌نویس» منتشر نشده آزمایش کنید. این قابلیت دیگر پشتیبانی نمی شود. در عوض، باید آن را در کانال توزیع آلفا یا بتا منتشر کنید. برای اطلاعات بیشتر، برنامه‌های پیش‌نویس دیگر پشتیبانی نمی‌شوند را ببینید.

موارد اضافی پاسخ سرور

برای کمک به برنامه شما در مدیریت دسترسی به برنامه در طول دوره بازپرداخت برنامه و ارائه اطلاعات دیگر، سرور صدور مجوز شامل چندین بخش از اطلاعات در پاسخ های مجوز است. به طور خاص، این سرویس مقادیر توصیه شده را برای مدت اعتبار مجوز برنامه، دوره مهلت امتحان مجدد، حداکثر تعداد مجاز تکرار مجدد و سایر تنظیمات ارائه می دهد. اگر برنامه شما از فایل‌های توسعه APK استفاده می‌کند، پاسخ شامل نام فایل، اندازه و نشانی‌های وب نیز می‌شود. سرور تنظیمات را به عنوان جفت کلید-مقدار در قسمت "اضافی" پاسخ مجوز اضافه می کند.

هر پیاده سازی Policy می تواند تنظیمات اضافی را از پاسخ مجوز استخراج کرده و در صورت نیاز از آنها استفاده کند. اجرای Policy پیش‌فرض LVL، ServerManagedPolicy ، به‌عنوان یک پیاده‌سازی کارآمد و تصویری از نحوه دریافت، ذخیره و استفاده از تنظیمات عمل می‌کند.

جدول 4. خلاصه تنظیمات مدیریت مجوز ارائه شده توسط سرور Google Play در پاسخ مجوز.

اضافی	توضیحات
VT	مهر زمانی اعتبار مجوز تاریخ/زمانی را مشخص می‌کند که پاسخ مجوز فعلی (در حافظه پنهان) منقضی می‌شود و باید دوباره در سرور مجوز بررسی شود. بخش زیر را در مورد مدت اعتبار مجوز مشاهده کنید.
GT	مهر زمانی دوره مهلت پایان دوره‌ای را مشخص می‌کند که طی آن یک خط‌مشی ممکن است اجازه دسترسی به برنامه را بدهد، حتی اگر وضعیت پاسخ RETRY شود. این مقدار توسط سرور مدیریت می شود، اما یک مقدار معمولی 5 روز یا بیشتر خواهد بود. بخش زیر را درباره دوره تلاش مجدد و حداکثر تعداد تلاش مجدد ببینید.
GR	حداکثر تعداد تلاش های مجدد. مشخص می‌کند که Policy باید چند بررسی متوالی مجوز RETRY را قبل از ممانعت از دسترسی کاربر به برنامه مجاز کند. این مقدار توسط سرور مدیریت می شود، اما یک مقدار معمولی "10" یا بالاتر خواهد بود. بخش زیر را درباره دوره تلاش مجدد و حداکثر تعداد تلاش مجدد ببینید.
UT	به روز رسانی مهر زمانی روز/زمانی را مشخص می کند که آخرین به روز رسانی این برنامه آپلود و منتشر شده است. سرور این مقدار اضافی را فقط برای پاسخ‌های LICENSED_OLD_KEYS برمی‌گرداند تا Policy اجازه دهد قبل از ممانعت از دسترسی کاربر به برنامه، تعیین کند که چقدر از زمان انتشار یک به‌روزرسانی با کلیدهای مجوز جدید گذشته است.
FILE_URL1 یا FILE_URL2	URL برای یک فایل توسعه (1 برای فایل اصلی، 2 فایل پچ است). از این برای دانلود فایل از طریق HTTP استفاده کنید.
FILE_NAME1 یا FILE_NAME2	نام فایل توسعه (1 برای فایل اصلی، 2 فایل پچ است). هنگام ذخیره فایل در دستگاه باید از این نام استفاده کنید.
FILE_SIZE1 یا FILE_SIZE2	اندازه فایل بر حسب بایت (1 برای فایل اصلی، 2 فایل پچ است). از این برای کمک به دانلود و اطمینان از اینکه فضای کافی در محل ذخیره سازی مشترک دستگاه قبل از دانلود در دسترس است استفاده کنید.

مدت اعتبار مجوز

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

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

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

• برای یک برنامه پولی، سرور دوره اعتبار مجوز اولیه را تنظیم می کند تا زمانی که برنامه قابل استرداد است، پاسخ مجوز معتبر باقی بماند. یک Policy مجوز در برنامه ممکن است نتیجه بررسی مجوز اولیه را در حافظه پنهان نگه دارد و نیازی به بررسی مجدد مجوز تا پایان دوره اعتبار ندارد.
• هنگامی که یک برنامه دیگر قابل بازپرداخت نیست، سرور دوره اعتبار طولانی تری را تعیین می کند - معمولاً چند روز.
• برای یک برنامه رایگان، سرور مدت اعتبار را روی یک مقدار بسیار بالا ( long.MAX_VALUE ) تنظیم می کند. این تضمین می کند که، مشروط بر اینکه Policy مشی مهر زمانی اعتبار را به صورت محلی ذخیره کرده باشد، در آینده نیازی به بررسی مجدد وضعیت مجوز برنامه نخواهد داشت.

اجرای ServerManagedPolicy از مهر زمانی استخراج شده ( mValidityTimestamp ) به عنوان شرط اولیه برای تعیین اینکه آیا باید وضعیت مجوز را با سرور قبل از اجازه دسترسی کاربر به برنامه، دوباره بررسی کرد یا خیر، استفاده می کند.

دوره تلاش مجدد و حداکثر تعداد تلاش مجدد

در برخی موارد، شرایط سیستم یا شبکه می‌تواند مانع از رسیدن بررسی مجوز برنامه به سرور صدور مجوز شود یا مانع از رسیدن پاسخ سرور به برنامه مشتری Google Play شود. به عنوان مثال، کاربر ممکن است زمانی که شبکه سلولی یا اتصال داده ای در دسترس نیست – مانند زمانی که در هواپیما هستید – یا زمانی که اتصال شبکه ناپایدار است یا سیگنال سلولی ضعیف است، برنامه ای را راه اندازی کند.

هنگامی که مشکلات شبکه مانع یا قطع یک بررسی مجوز می شود، سرویس گیرنده Google Play با بازگرداندن یک کد پاسخ RETRY به روش processServerResponse() Policy ، برنامه را مطلع می کند. در مورد مشکلات سیستم، مانند زمانی که برنامه نمی تواند با پیاده سازی ILicensingService Google Play متصل شود، خود کتابخانه LicenseChecker متد Policy processServerResponse() را با کد پاسخ RETRY فراخوانی می کند.

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

سرور Google Play به برنامه کمک می‌کند تا با تنظیم «دوره مهلت» تلاش مجدد و تعداد حداکثر توصیه‌شده، مجوز را تحت شرایط خطا مدیریت کند. سرور این مقادیر را در تمام پاسخ‌های بررسی مجوز گنجانده و آنها را به عنوان موارد اضافی تحت کلیدهای GT و GR اضافه می‌کند.

Policy برنامه می تواند موارد اضافی GT و GR را استخراج کند و از آنها برای اجازه دسترسی مشروط به برنامه استفاده کند، به شرح زیر:

• برای بررسی مجوز که منجر به پاسخ RETRY می‌شود، Policy باید کد پاسخ RETRY را در حافظه پنهان کند و تعداد پاسخ‌های RETRY را افزایش دهد.
• این Policy باید به کاربر اجازه دسترسی به برنامه را بدهد، مشروط بر اینکه دوره مهلت امتحان مجدد هنوز فعال باشد یا به حداکثر تعداد تلاش‌های مجدد نرسیده باشد.

ServerManagedPolicy از مقادیر GT و GR ارائه شده توسط سرور همانطور که در بالا توضیح داده شد استفاده می کند. مثال زیر مدیریت مشروط پاسخ‌های retry را در متد allow() نشان می‌دهد. تعداد پاسخ‌های RETRY در روش processServerResponse() حفظ می‌شود و نشان داده نمی‌شود.

کاتلین

fun allowAccess(): Boolean {
    val ts = System.currentTimeMillis()
    return when(lastResponse) {
        LICENSED -> {
            // Check if the LICENSED response occurred within the validity timeout.
            ts <= validityTimestamp  // Cached LICENSED response is still valid.
        }
        RETRY -> {
            ts < lastResponseTime + MILLIS_PER_MINUTE &&
                    // Only allow access if we are within the retry period
                    // or we haven't used up our max retries.
                    (ts <= retryUntil || retryCount <= maxRetries)
        }
        else -> false
    }
}

جاوا

public boolean allowAccess() {
    long ts = System.currentTimeMillis();
    if (lastResponse == LicenseResponse.LICENSED) {
        // Check if the LICENSED response occurred within the validity timeout.
        if (ts <= validityTimestamp) {
            // Cached LICENSED response is still valid.
            return true;
        }
    } else if (lastResponse == LicenseResponse.RETRY &&
                ts < lastResponseTime + MILLIS_PER_MINUTE) {
        // Only allow access if we are within the retry period
        // or we haven't used up our max retries.
        return (ts <= retryUntil || retryCount <= maxRetries);
    }
    return false;
}