اضافه کردن خرید درون‌برنامه‌ای در جاوا

مقدمه

خرید درون‌برنامه‌ای مایکت API ساده‌ای برای شما فراهم کرده تا به راحتی بتوانید امور خرید را مدیریت کنید. این نوشته تمام نیازمندی های شما برای پیاده سازی خرید درون برنامه ای در کد اندروید را شرح میدهد، هر چند ممکن است برای آشنایی بیشتر برای مفاهیم و مراحل فرآیند خرید درون برنامه ای، سایر مستندات این پایگاه دانش را مطالعه کنید.

قبل از شروع، توصیه می‌شود برای آشنایی با مفاهیم اصلی این نوشته را بخوانید تا پیاده‌سازی برای شما راحت‌تر شود.
توجه: برای دیدن یک پیاده‌سازی کامل و نحوه اجرای درست، اینجا را ببینید. در آن نوشته، فرآیند پیاده‌سازی خرید درون‌برنامه‌ای شرح داده شده، که حاوی کلاس‌های کمکی برای انجام وظایف کلیدی است، مانند راه‌اندازی اولیه، ارسال درخواست‌ها، بررسی پاسخ‌های مایکت، و مدیریت threadهای پس‌زمینه تا بتوانید خرید درون‌برنامه‌ای را از activity اصلی خود صدا بزنید. 

برای پیاده‌سازی خرید درون‌برنامه‌ای در برنامه‌تان شما باید موارد زیر را انجام دهید:

  1. کتابخانه خرید درون‌برنامه‌ای را به برنامه خود اضافه کنید.
  2. فایل AndroidManifest.xml را بروزرسانی کنید.
  3. یک ServiceConnection بسازید و آن را به IInAppBillingService متصل کنید.
  4. درخواست‌های خرید درون برنامه را از برنامه خود به IInAppBillingService بفرستید.
  5. پاسخ‌های دریافتی از مایکت را بررسی کنید.

آشنایی با مدل‌های پیاده‌سازی خرید درون‌برنامه‌ای

سه مدل کلی برای کسب درآمد از طریق خرید درون‌برنامه‌ای وجود دارد، محصولات مصرف‌شدنی، مصرف‌نشدنی و اشتراکی. محصولات مصرف‌شدنی محصولاتی است که کاربر آن‌ها را استفاده می‌کند و سپس، دوباره اقدام به خرید می‌کند. مثال اینگونه محصولات سکه، GEM و… است. محصولات مصرف‌نشدنی محصولاتی هستند که کاربران یک بار برای همیشه مبلغی بابت آن‌ها پرداخت می‌کند، مانند باز کردن مراحلی از بازی، حذف تبلیغات و اکانت پریمیوم. محصولات اشتراکی برای مدت زمانی محدود به کاربر تحویل داده می‌شود. مثلا اشتراک یک ماههٔ یک برنامهٔ موسیقی یا اشتراک یک سالهٔ یک کتابخوان دیجیتالی. در این مدل، مدت زمان مجاز برای استفاده از برنامه توسط استور کنترل می‌شود و نیازی به هیچ پیاده‌سازی جهت کنترل زمان ندارند. شایان ذکر است در حال حاضر مدل اشتراکی در مایکت پشتیبانی نمی شود.

بارگذاری برنامه در پنل توسعه‌دهندگان

برای شروع باید یک حساب توسعه‌دهنده بسازید و برنامهٔ خود را در پنل توسعه‌دهندگان تعریف کنید. سپس،‌ کافیست کلید رمز عمومی برنامهٔ خود را دریافت و محصولات خود را تعریف نمایید. توجه کنید که برای اضافه کردن برنامه به پنل توسعه‌دهندگان مایکت نیازی نیست حتما apk برنامهٔ خود را بارگذاری کنید. تنها کافی است، در قسمت اضافه کردن برنامه یک شناسه (Packagename) برای برنامهٔ خود رزرو کنید.

دریافت فایل‌های کمکی

برای شروع باید فایل‌های کمکی را دانلود و به برنامهٔ خود اضافه کنید. برای این کار کافی است ابتدا برنامه نمونه TrivialDrive را از اینجا دانلود کنید (یا در Github مشاهده نمایید) و مراحل زیر را انجام دهید:

۱. ابتدا پوشهٔ util را به برنامهٔ خود منتقل کنید.

۲. فایل IInAppBillingService.aidl را به پوشهٔ src/main/aidl/com.android.vending.billing کپی کنید.

IInAppBillingService.aidl یک فایل AIDL است که رابطی برای سرویس خرید درون‌برنامه‌ای مایکت تعریف می‌کند. شما از این رابط برای برقراری ارتباط با مایکت استفاده می‌کنید. فایل را در آدرس /src/com/android/vending/billing/IInAppBillingService.aidl پیدا می‌کنید.

بعد از انجام این دو مرحله ساختار پروژه شما باید اینچنین باشد:

توجه کنید، ساختار تمام پروژه‌های اندرویدی یکسان نیست. در پروژه‌هایی که با Android Studio ایجاد شده‌اند، باید فایل‌های AIDL را در پوشه‌ی java/aidl کپی داد. ولی در ساختار‌های قدیمی مانند پروژه‌هایی که با Eclipse ایجاد شده‌اند، باید فایل‌های AIDL را در آدرس خودش (پکیجی که در خود فایل آورده شده است) و در کنار دیگر فایل‌های Java کپی کرد:src/com/android/vending/licensing

اگر از محیط Eclipse استفاده می‌کنید:

  • اگر قبلا پروژه خود را ساخته‌اید آن را در Eclipse باز کنید، در غیر این صورت یک Android Application Project جدید بسازید.
  • در پوشه /src روی File > New > Package کلیک کنید تا یک package جدید ایجاد کنید و نام آن را com.android.vending.billing قرار دهید.
  • فایل IInAppBillingService.aidl را که در مرحله قبل گرفته‌اید در بسته src/com.android.vending.billing/ کپی کنید.

۳. دسترسی زیر را در قسمت دسترسی‌های فایل AndroidManifest.xml برنامهٔ خود اضافه کنید.

<uses-permission android:name="ir.mservices.market.BILLING" />

خرید درون‌برنامه‌ای وابسته به برنامه مایکت است، که همه ارتباطات بین برنامه شما و سرور مایکت را مدیریت خواهد کرد. برای استفاده از برنامه مایکت برنامه شما باید مجوز مناسب را درخواست کند. شما می‌توانید این کار را با اضافه کردن مجوز ir.mservices.market.BILLING به فایل AndroidManifest.xml انجام دهید. در صورتی که برنامه شما مجوز خرید درون‌برنامه‌ای را درخواست نکرده باشد، درخواست‌اش برای ارتباط با مایکت پذیرفته نمی‌شود و برنامه شما با خطا مواجه می‌شود.شما می‌توانید برای برنامه خود اجازه‌های لازم را با قرار دادن کد بالا در فایل AndroidManifest.xml صادر کنید. 

۴. پروژهٔ شما باید بدون خطا Build شود.

حال باید فایلی با نام IInAppBillingService.java در پوشه /gen خود داشته باشید. دقت کنید که شما این فایل را دستی نمی‌سازید بلکه بعد در طی build کردن ساخته می‌شود.

مراحل پیاده‌سازی

ساختن IabHelper

برای شروع کار باید یک Instance از IabHelper ایجاد کنیم. با توجه به اینکه در متد‌ها و Callbackهای مختلف نیاز دارید تا به این Object دسترسی داشته باشید، بهتر است این Instance را به صورت یک فیلد در Activity خود تعریف کنید. برای ساختن IabHelper نیاز است تا کلید رمز عمومی را (که از پنل توسعه‌دهندگان دریافت کرده‌اید) به همراه Context به Constructor کلاس IabHelper بدهید:

mHelper = new IabHelper(context, base64EncodedPublicKey);

تنظیم Logger

کلاس IabHelper لاگ‌های خود را با تگ “IabHelper” در خروجی لاگ‌های اندروید (LogCat) می‌نویسد. شما می‌توانید این لاگ‌ها را فعال یا غیر فعال نمایید:

mHelper.enableDebugLogging(true);
توجه کنید که لاگ‌ها را در حالت debug فعال و قبل از انتشار (release) غیر فعال کنید. برای این کار می‌توانید از تنظیمات Gradle استفاده نمایید.

اتصال به سرویس مایکت (startSetup)

برای اتصال به سرویس پرداخت درون‌برنامه‌ای مایکت کافی است از متد startSetup استفاده کنید. این متد را باید قبل از هر متد دیگری صدا بزنید و در صورت متصل شدن به سرویس می‌توانید از سرویس پرداخت درون‌برنامه‌ای مایکت استفاده کنید. حال یک Callback از جنس OnIabSetupFinishedListener در پارامتر‌ این متد پیاده‌سازی کنید:

mHelper.startSetup(new IabHelper.OnIabSetupFinishedListener() {
            public void onIabSetupFinished(IabResult result) {
                 
            }
        });
}

پس از تلاش برای اتصال به سرویس، متد onIabSetupFinished همراه با یک IabResult فراخوانی می‌شود و نتیجه را اعلام می‌کند. در صورتی که خروجی متد isSuccess در IabResult برابر TRUE بود، اتصال با موفقیت انجام شده است. در غیر این صورت برنامهٔ شما نتوانسته به سرویس مایکت متصل شود که در این صورت می‌توانید از متد getMessage برای علت خطا استفاده کنید.

توجه کنید که در تمامی Callbackهای کلاس IabHelper باید به دلیل تاخیر در جواب حتما چک کنید که Instance این Object برابر با Null نشده باشد: if (mHelper == null) return;

به‌روز کردن اطلاعات خرید(queryInventory)

به محض متصل شدن به سرویس مایکت (یعنی زمانی که متد isSuccess در IabResult برابر TRUE بود) باید خرید‌های کاربر را به‌روز کنید. به‌روز کردن خرید کاربر‌ها در مدل‌های محصولات مختلف مفهوم‌های مختلفی دارد:

برای محصولات مصرف‌شدنی این معنی را می‌دهد که به هر علت یک خرید مصرف نشده وجود دارد که باید مصرف شود و به کاربر تحویل داده شود. مثلا فرض کنید که در فرایند خرید قبلی، کاربر با مشکل مواجه می‌شود یا به هر دلیلی قبل از مصرف کردن محصول، برنامهٔ شما بسته می‌شود و یا ارتباط کاربر قطع می‌گردد. در این صورت باید در اجرای بعدی این محصول را مصرف کنید و به کاربر تحول دهید.

علت به‌روز کردن محصولات برای محصولات مصرف‌نشدنی این است که از این طریق متوجه می‌شوید که کاربر محصول شما را خریداری کرده است یا نه. در صورتی که خریداری کرده بود امکان مورد نظر (مثلا حذف تبلیغات یا مراحل کامل بازی یا …) را برای او فعال می‌کنید.

در مورد محصولات اشتراکی هم از این طریق متوجه می‌شوید که کاربر هنوز مشترک برنامهٔ شما هست یا خیر. در صورتی که زمان اشتراک تمام نشده بود در queryInventory به شما خبر داده می‌شود.

در واقع می‌توان گفت در queryInventory، تمام محصولاتی که مصرف نکرده‌اید، همیشه برمی‌گردد. در صورتی که مصرف‌شدنی بود که باید همان‌جا مصرف شود و بعد تحویل کاربر شود و در صورتی که مصرف‌نشدنی یا اشتراکی بود، باید به کاربر تحویل داده شود. 

همچنین با استفاده از queryInventory می‌توانید اطلاعات مربوط به محصولات خود (نام محصول، توضیحات، قیمت و …) که در پنل توسعه‌دهندگان وارد نموده‌اید را دریافت کنید. مثلا فرض کنید که بعد از انتشار خود قیمت یا نام یکی از محصولات خود را تغییر می‌دهید. با استفاده از این قابلیت می‌توانید در UI برنامهٔ خود همیشه مشخصات محصولی را نشان دهید که در پنل توسعه‌دهندگان مایکت قرار دارد و با تغییر آن برنامهٔ شما نیز تغییر می‌کند.

برای به‌روز کردن خرید‌ها باید نام محصولات را به همراه یک Callback از جنس QueryInventoryFinishedListener به متد queryInventoryAsync از کلاس IabHelper بدهید تا فرایند به‌روز کردن آغاز شود:

try {
    mHelper.queryInventoryAsync(true, itemSkus, subSkus, mGotInventoryListener);
} catch (IabAsyncInProgressException e) {
    Log.e(TAG, "Error querying inventory. Another async operation in progress.");
}

متد queryInventoryAsync دارای چهار پارامتر است که به ترتیب:

۱. boolean querySkuDetails: در صورتی که می‌خواهید اطلاعات محصولات به‌روز شود (نام، قیمت و …) این Boolean را برابر TRUE قرار دهید. توجه کنید که در صورتی که نمی‌خواهید از این قابلیت استفاده کنید این مقدار را برابر FALSE قرار دهید تا سرویس اضافه‌ای صدا نشود.

۲. List<String> moreItemSkus: لیستی از ID محصولات فروشی (مصرف‌شدنی و مصرف‌نشدنی). در صورتی که برنامهٔ شما محصولات فروشی ندارد این لیست را برابر NULL قرار دهید.

۳. List<String> moreSubsSkus: لیستی از ID محصولات اشتراکی. در صورتی که برنامهٔ شما محصولات اشتراکی ندارد این لیست را برابر NULL قرار دهید.

۴. QueryInventoryFinishedListener listener: برای جواب این سرویس Callbackی از جنس QueryInventoryFinishedListener ست شود.

توجه کنید که در یک لحظه می‌تواند فقط یک درخواست به سرویس مایکت زد. در صورتی که درخواستی در حال اجرا باشد و شما درخواست دیگری را صدا بزنید، خطای IabAsyncInProgressException رخ می‌دهد.

نتیجهٔ این درخواست با دو Object با نام‌های IabResult و Inventory در متد onQueryInventoryFinished بازمی‌گردد. از IabResult موفق بودن/نبودن درخواست مشخص می‌شود و خرید‌های به‌روز شده و اطلاعات محصولات در Inventory قرار می‌گیرد. Inventory شامل دو Map با نام‌های mSkuMap و mPurchaseMap هست. خرید‌های به‌روز‌ شده در mPurchaseMap قرار می‌گیرد که با استفاده از متد getPurchase در کلاس Inventory می‌توانید متوجه شوید برای محصول مورد نظرتان خرید به‌روز شده‌ای وجود دارد یا خیر. همچنین می‌توانید با استفاده از متد getAllPurchases به تمامی لیستی (از جنس Purchase) درسترسی پیدا کنید.

همچنین می‌توانید اطلاعات خرید که در پنل توسعه‌دهندگان تنظیم کرده‌اید را در mSkuMap بیابید. توجه کنید در صورتی که مقدار querySkuDetails را برابر FALSE قرار دهید این Map برابر با NULL خواهد بود. با استفاده از متد getSkuDetails در کلاس Inventory می‌توانید به اطلاعات خرید محصول مورد نظر دسترسی پیدا کنید و UI برنامهٔ خود را به‌روز نمایید.

مفهوم queryInventory، تجمیع دو مفهوم getPurchases و getSkuDetail است. در واقع با هر queryInventory، یک getPurchases زده می‌شود و در صورتی که فیلد querySkuDetails را TRUE قرار دهید، getSkuDetail هم صدا زده می‌شود. برای آشنایی بیشتر با مفاهیم این APIها ویدئو آموزشی مقدماتی را ببینید یا مستند آشنایی با خرید درون‌برنامه‌ای مایکت را مطالعه نمایید.

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

IabHelper.QueryInventoryFinishedListener mGotInventoryListener = new IabHelper.QueryInventoryFinishedListener() {
    public void onQueryInventoryFinished(IabResult result, Inventory inventory) {
 
        // Have we been disposed of in the meantime? If so, quit.
        if (mHelper == null) return;
 
        // Is it a failure?
        if (result.isFailure()) {
            complain("Failed to query inventory: " + result);
            return;
        }
 
        // (1)
        // Do we have the premium upgrade?
        Purchase premiumPurchase = inventory.getPurchase(SKU_PREMIUM);
        Log.d(TAG, "User is " + (mIsPremium ? "PREMIUM" : "NOT PREMIUM"));
         
        // (2)
        // First find out which subscription is auto renewing
        Purchase gasMonthly = inventory.getPurchase(SKU_INFINITE_GAS_MONTHLY);
        Purchase gasYearly = inventory.getPurchase(SKU_INFINITE_GAS_YEARLY);
 
        // (3)
        // Check for gas delivery -- if we own gas, we should fill up the tank immediately
        Purchase gasPurchase = inventory.getPurchase(SKU_GAS);
        consume(SKU_GAS)
        updateUi();
        Log.d(TAG, "Initial inventory query finished; enabling main UI.");
    }
};

همانطور که در مثال بالا می‌بینید در قسمت (1) محصول با شناسهٔ SKU_PREMIUM را از خرید‌های به‌روز شده جست‌وجو می‌کند و در صورتی که premiumPurchase برابر با NULL نباشد این محصول مصرف‌نشدنی به کاربر تحویل می‌شود.

در قسمت (2) برای محصولات اشتراکی جست‌وجو می‌شود در صورتی که اشتراک ماهیانه یا سالیانه کاربر فعال باشد، مقدار gasMonthly یا gasYearly مخالف NULL خواهد بود.

در قسمت (3) برای محصول مصرف‌شدنی SKU_GAS جست‌وجو انجام می‌شود و در صورت NULL نبودن gasPurchase این محصول مصرف می‌شود (Consume) و سپس به کاربر تحویل داده خواهد شد. در خصوص Consume در ادامه توضیح خواهیم داد.

فیلد‌های آبجکت Purchase به صورت زیر است:

توضیحاتTypeنام
نوع محصول (inapp/subs)StringmItemType
شمارهٔ فاکتور خریدStringmOrderId
پکیج‌نیم برنامهٔ شماStringmPackageName
ID محصولStringmSku
Timestamp زمان خریدlongmPurchaseTime
وضعیت خرید (مصرف‌شده / مصرف نشده)intmPurchaseState
Developer payloadStringmDeveloperPayload
توکن خرید این محصولStringmToken
رشتهٔ JSON که از سرور مایکت برمی‌گرددStringmOriginalJson
Signiture رشتهٔ mOriginalJsonStringmSignature
فعال/غیر‌فعال بودن Auto RenewbooleanmIsAutoRenewing

با توجه به اینکه اولین درخواستی که باید بعد از اتصال به سرویس مایکت صدا زده شود در خواست queryInventoryAsync است، بدنهٔ کلی متد startSetup به صورت زیر خواهد بود (با فرض اینکه لیست‌های subSkus و itemSkus با مقادیر IDهای محصولات ساخته شده است و mGotInventoryListener نیز پیاده‌سازی شده است):

    mHelper.startSetup(new IabHelper.OnIabSetupFinishedListener() {
        public void onIabSetupFinished(IabResult result) {
            Log.d(TAG, "Setup finished.");
 
            if (!result.isSuccess()) {
                // Oh noes, there was a problem.
                complain("Problem setting up in-app billing: " + result);
                return;
            }
 
            // Have we been disposed of in the meantime? If so, quit.
            if (mHelper == null) return;
             
            Log.d(TAG, "Setup successful. Querying inventory.");
            try {
                mHelper.queryInventoryAsync(true, itemSkus, subSkus, mGotInventoryListener);
            } catch (IabAsyncInProgressException e) {
                complain("Error querying inventory. Another async operation in progress.");
            }
        }
    });
}
بسیار مهم: در صورتی که queryInventory را در لحظهٔ شروع برنامه صدا نزنید ممکن است از کاربران برنامهٔ‌ شما مبلغی کاسته شود و هیچگاه، محصول تحویل نگردد. برخی توسعه‌دهندگان برای به‌روز کردن خرید‌ها از دکمه‌ای با نام «به‌روزرسانی خرید‌ها» در برنامهٔ خود استفاده می‌کنند که در آن queryInventory را فراخوانی می‌کنند. توجه کنید که حتی با پیاده‌سازی این دکمه باید در لحظهٔ شروع برنامه خرید‌های کاربر را به‌روز کنید. این مشکل در بین توسعه‌دهندگان سرویس پرداخت درون‌برنامه‌ای بسیار متداول است.

فرستادن درخواست‌های خرید درون‌برنامه‌ای

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

فرض کنید که برنامهٔ شما باز شده و با موفقیت به سرویس مایکت متصل گردیده است. کاربر وارد صفحهٔ فروشگاه برنامه می‌شود و لیستی از محصولات شما را به همراه قیمت‌های آن‌ها مشاهده می‌کند (لیستی که با استفاده از mSkuMap در کلاس Inventory ساخته‌اید). در کنار هر آیتم لیست یک دکمهٔ خرید وجود دارد. کاربر با زدن دکمهٔ خرید وارد فرایند خرید آن محصول می‌شود. شروع فرایند خرید تمامی محصولات درون‌برنامه‌ای با استفاده از متد launchPurchaseFlow در کلاس IabHelper، به صورت زیر است:

try {
    mHelper.launchPurchaseFlow(this, SKU_PREMIUM, RC_REQUEST, mPurchaseFinishedListener, payload);
} catch (IabAsyncInProgressException e) {
    complain("Error launching purchase flow. Another async operation in progress.");
}

متد launchPurchaseFlow پارامتر‌های زیر را به ترتیب می‌پذیرد:

۱. Activity act: اکتیویتی برنامهٔ شما که فرایند خرید در آن انجام می‌شود.

۲. String sku: شناسهٔ محصول درون‌برنامه‌ای که قصد خرید آن را دارید.

۳. int requestCode: یک Integer به عنوان requestCode جهت چک کردن در onActivityResult

۴. OnIabPurchaseFinishedListener listener: یک Callback از جنس OnIabPurchaseFinishedListener که پایان فرایند خرید را خبر می‌دهد.

۵. String developerPayload: مقدار Developer payload این خرید. از رشته developerPayload برای مشخص کردن هر اطلاعات اضافی که مایلید مایکت به همراه اطلاعات خرید برای شما برگرداند، استفاده می‌شود.

زمانی که با استفاده از launchPurchaseFlow فرایند خرید را آغاز می‌کنید، یک Activity از مایکت روی برنامهٔ شما باز می‌شود و مشخصات محصول به همراه درگاه‌های خرید را به کاربر نمایش می‌دهد تا کاربر خرید را انجام دهد.

زمانی که خرید به صورت موفق یا ناموفق به پایان رسید، مایکت با requestCodeی که در launchPurchaseFlow تعیین نموده‌اید، متد onActivityResult اکتیویتی برنامهٔ شما را صدا می‌زند.

شما باید به صورت زیر این رویداد را به IabHelper خود اطلاع دهید:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    Log.d(TAG, "onActivityResult(" + requestCode + "," + resultCode + "," + data);
    if (mHelper == null) return;
 
    // Pass on the activity result to the helper for handling
    if (!mHelper.handleActivityResult(requestCode, resultCode, data)) {
        super.onActivityResult(requestCode, resultCode, data);
    }
    else {
        Log.d(TAG, "onActivityResult handled by IABUtil.");
    }
}

سپس IabHelper پس از بررسی Signature خرید با کلید رمز عمومی شما، OnIabPurchaseFinishedListener را فراخوانی می‌کند. در متد onIabPurchaseFinished دو Object با نام‌های IabResult و Purchase باز می‌گردد. IabResult نشان می‌دهد که خرید موفق انجام شده است یا خیر و در صورت موفقیت، مشخصات محصول خریداری شده در Purchase قرار داده می‌شود. یک نمونه از پیاده‌سازی این Callback به صورت زیر است:

IabHelper.OnIabPurchaseFinishedListener mPurchaseFinishedListener = new IabHelper.OnIabPurchaseFinishedListener() {
    public void onIabPurchaseFinished(IabResult result, Purchase purchase) {
        Log.d(TAG, "Purchase finished: " + result + ", purchase: " + purchase);
 
        // if we were disposed of in the meantime, quit.
        if (mHelper == null) return;
 
        if (result.isFailure()) {
            complain("Error purchasing: " + result);
            setWaitScreen(false);
            return;
        }
 
        Log.d(TAG, "Purchase successful.");
 
        // handling purchase
    }
};

پس از اینکه خرید با موفقیت انجام شد، با توجه به مدل محصول، آن را به کاربر تحویل دهید. اگر محصول برنامهٔ شما مصرف‌نشدنی یا اشتراکی است باید آن را پس از onIabPurchaseFinished موفقیت آمیز به کاربر تحویل دهید. در صورتی که محصول برنامهٔ شما مصرف‌شدنی است ابتدا باید آن را Consume کنید و سپس به کاربر تحویل دهید. Consume کردن یک محصول باعث می‌شود که آن محصول، در لیست queryInventory (محصولات به‌روز شده) بازنگردد، بنابراین محصولات مصرف‌نشدنی و اشتراکی را Consume نکنید.

توصیه امنیتی: وقتی که شما یک درخواست خرید ارسال می‌کنید، یک رشته‌ی token بسازید که به طور منحصر به فرد این درخواست خرید را مشخص کند و آن را در developerPayload قراد دهید. شما می‌توانید از یک رشته‌ای که تصادفی تولید شده به عنوان token استفاده کنید. هنگامی که شما پاسخ خرید را از مایکت دریافت می‌کنید مطمئن شوید که امضای دیجیتالی، orderId، و رشته developerPayload داده‌های بازگشتی را بررسی می‌کنید. برای امنیت بیشتر، شما باید این کار را بر روی سرورهای امن خود انجام دهید. اطمینان حاصل کنید که orderId یک مقدار منحصر به فرد باشد و شما قبلا آن را پردازش نکرده‌اید و رشته developerPayload با tokenی که قبلاً با درخواست خرید فرستاده‌اید مطابقت داشته باشد.

مصرف نمودن یک خرید

هنگامی که محصولی توسط کاربر خریداری می‌شود مالک آن تلقی می‌شود و امکان خرید دوباره آن را نخواهد داشت. شما باید یک درخواست مصرف به مایکت ارسال کنید تا مایکت اجازه خرید دوباره محصول را به کاربر بدهد.

مهم: تنها محصولات «مصرف شدنی» را می‌توان مصرف کرد، درخواست مصرف برای محصولات «مصرف نشدنی» کد پاسخ خطا برمی‌گرداند.اینکه شما چگونه مصرف شدن محصول در برنامه خود را پیاده می‌کنید به عهده شماست. معمولا شما محصولاتی را مصرف می‌کنید که اثر موقت در برنامه دارند و کاربر ممکن است بخواهد چندین بار آنها را بخرد ( برای مثال خرید پول در یک بازی). اما محصولاتی که با یک بار خرید اثر دائمی دارند را مصرف نمی‌کنید (مانند ارتقای حساب کاربری در برنامه). 

برای Consume کردن یک محصول، از متد consumeAsync به همراه یک Purchase و یک Callback از جنس OnConsumeFinishedListener استفاده کنید:

try {
    mHelper.consumeAsync(purchase, mConsumeFinishedListener);
} catch (IabAsyncInProgressException e) {
    complain("Error consuming gas. Another async operation in progress.");
}

یک نمونه از پیاده‌سازی OnConsumeFinishedListener به صورت زیر است:

IabHelper.OnConsumeFinishedListener mConsumeFinishedListener = new IabHelper.OnConsumeFinishedListener() {
    public void onConsumeFinished(Purchase purchase, IabResult result) {
        Log.d(TAG, "Consumption finished. Purchase: " + purchase + ", result: " + result);
 
 
        // if we were disposed of in the meantime, quit.
        if (mHelper == null) return;
 
        if (result.isSuccess()) {
            // successfully consumed, so we apply the effects of the item in our
            // game world's logic, which in our case means filling the gas tank a bit
            Log.d(TAG, "Consumption successful. Provisioning.");
        }
        else {
            complain("Error while consuming: " + result);
        }
        Log.d(TAG, "End consumption flow.");
    }
};

در متد onConsumeFinished دقیقا مانند onIabPurchaseFinished، یک Purchase برای مشخصات خرید و یک IabResult برای نتیجهٔ Consume برمی‌گردد. در صورتی که isSuccess برابر TRUE بود، می‌توانید محصول را به کاربر تحویل دهید (مثلا سکهٔ او را افزایش دهید).

این مسئولیت شماست که مزایای هر محصول را به کاربر ارائه دهید. به عنوان مثال اگر یک کاربر در بازی شما پول یا سکه خریداری کند، شما باید مقدار پول یا تعداد سکه او را بروز رسانی نمایید.

توصیه امنیتی: شما باید قبل از ارائه مزایای یک محصول مصرف شدنی، یک درخواست مصرف را به مایکت ارسال نمایید و مطمن شوید که مایکت درخواست مصرف را تایید کرده است.

محصولات اشتراکی

مایکت از اشتراک پشتیبانی نمی‌کند. برای اطلاعات بیشتر در این زمینه می‌توانید از تیم پشتیبانی مایکت به آدرس ایمیل developer@myket.ir کمک بگیرید.

ارسال اطلاعات خرید به سرور

در صورتی که تحویل محصولات در منطق برنامهٔ شما سمت سرور انجام می‌شود، لازم است که اطلاعات خرید و کاربر خود را به سرور ارسال کنید. پیشنهاد می‌شود که این کار را پس از انجام موفق Consume در OnConsumeFinishedListener انجام دهید. برای این کار کافی است که اطلاعات خرید را با استفاده از متد getOriginalJson در کلاس Purchase به سرور ارسال کنید. توجه کنید که فیلد token در این Json برای تمام خرید‌های برنامهٔ شما یکتا است و می‌توانید به عنوان کلید از آن استفاده کنید. توجه کنید که لازم است حتما در کنار این Json مقدار Signature را نیز (با استفاده از متد getSignature در کلاس Purchase) برای سرور ارسال کنید و با استفاده از کلید رمز عمومی که از پنل توسعه‌دهندگان مایکت دریافت نموده‌اید، با هم تطبیق دهید.

آماده‌سازی جهت بستن برنامه (onDestroy)

در onDestroy اکتیویتی برنامهٔ خود که یک Instance از IabHelper را در آن نگه داشته‌اید، کد‌ زیر را بنویسید:

@Override
public void onDestroy() {
    super.onDestroy();
 
 
    Log.d(TAG, "Destroying helper.");
    if (mHelper != null) {
        mHelper.disposeWhenFinished();
        mHelper = null;
    }
}

برنامهٔ آموزشی TrivialDrive

برنامهٔ آموزشی TrivialDrive توسط گوگل طراحی شده است که ما با تغییرات آن را به سرویس پرداخت درون‌برنامه‌ای مایکت متصل کرده‌ایم. سورس این برنامه می‌توانید از اینجا دانلود کنید و یا در Github مشاهده نمایید.

در این برنامه چهار دکمه وجود دارد. با استفاده از دکمهٔ سبز رنگ (Drive) می‌توانید بازی کنید و مشاهده نمایید که شاخص بنزین شما کم می‌شود. در صورتی که بنزین شما تمام شود دیگر نمی‌توانید بازی کنید و مجبور به خرید بنزین می‌شوید. با دکمهٔ زرد رنگ (Buy GAS) می‌توانید بنزین بخرید. توجه کنید بنزین در این مثال یک محصول مصرف‌شدنی است. با استفاده از دکمهٔ آبی رنگ (Upgrade my Car) می‌توانید محصول مصرف‌نشدنی بخرید و برای همیشه بنزین داشته باشید و با استفاده از دکمهٔ قرمز رنگ (Get Infinite GAS) می‌توانید اشتراک یک ماهه یا یک ساله بخرید.

ملاحظات امنیتی

برای جلوگیری از دسترسی غیر مجاز به امکانات غیر رایگان برنامهٔ شما لازم است که موارد امنیتی زیر را در نظر بگیرید.

نگه‌داری از محتوا

سعی کنید از سروری برای نگه‌داری محتوای غیر رایگان برنامهٔ خود استفاده کنید و پس از خرید کاربر با استفاده از وب‌سرویس آن را به کلاینت خود منتقل کنید.  همچنین پس از دریافت محتوا از سرور، آن را به صورت رمز شده در حافظه دستگاه نگه دارید و از کلیدی منحصر به همان دستگاه برای دسترسی به اطلاعات رمز شده استفاده کنید. در نظر داشته باشید که در صورتی که محتوای برنامهٔ شما درون فایل apk باشد، امن نیست و می‌توان به آن دسترسی داشت.

تایید امضای دیجیتالی روی سرور

برای فرستادن اطلاعات به سِرور برنامهٔ خود، حتما رشتهٔ Json را به همراه Signature دریافتی از مایکت (با استفاده از متد getSignature و getOriginalJson در کلاس Purchase) ارسال کنید و فرایند تایید امضای دیجیتال را با کلید رمز عمومی (PublicKey) را در سِرور نیز انجام دهید. توجه کنید فرایند تایید امضای دیجیتال در متد verifyPurchase در کلاس Security انجام می‌شود و دقیقا مانند همین کار را باید در سرور خود نیز انجام دهید:

public static boolean verifyPurchase(String base64PublicKey, String signedData, String signature) {
    if (TextUtils.isEmpty(signedData) || TextUtils.isEmpty(base64PublicKey) ||
            TextUtils.isEmpty(signature)) {
        Log.e(TAG, "Purchase verification failed: missing data.");
        return false;
    }
 
    PublicKey key = Security.generatePublicKey(base64PublicKey);
    return Security.verify(key, signedData, signature);
}

به هم ریختگی کد‌ها

برای جلوگیری از عملکرد برنامه‌های مخرب، حتما از سورس کد برنامهٔ خود محافظت کنید. ابتدا باید در کد خود بهم‌ریختگی (obfuscation) ایجاد کنید. برای این کار می‌توانید از ابزار‌هایی نظیر ProGuard استفاده کنید. همچنین مقادیر حساس نظیر کلید رمز عمومی (Public key) را به صورت رشته‌ای ثابت در کد خود قرار ندهید و سعی کنید این رشته‌ها را در زمان اجرای برنامه بسازید (مانند XOR با چند رشتهٔ دیگر). توجه کنید سورس کد‌ کمکی که در اختیار شما قرار دارد می‌تواند در اختیار هکر‌ها نیز قرار گیرد بنابراین بهتر است ساختار پروژه و ترتیب متد‌ها را تغییر دهید تا برنامهٔ شما الگوی متفاوتی داشته باشد و پیدا کردن آن زمان‌بَر شود.

استفاده از Developer payload

در سرویس پرداخت درون‌برنامه‌ای مایکت می‌توانید همراه درخواست خرید یک رشته‌‌، موسوم به developer payload هم ارسال کنید. این رشته می‌تواند به عنوان یک شناسهٔ منحصر به فرد از سمت شما برای این خرید در نظر گرفته شود. بعد از اتمام مراحل خرید این رشته را در کلاس Purchase به برنامهٔ شما بازمی‌گرداند. همچنین زمانی که خرید‌های خود را به‌روز می‌کنید، مایکت این رشته را نیز همراه دیگر جزئیات خرید برمی‌گرداند.
شما باید توکن رشته‌ای استفاده کنید که به برنامه‌تان در تشخیص کاربری که خرید را انجام داده کمک کند. به این ترتیب بعداً می‌توانید بفهمید که خرید مورد نظر برای کاربر معتبر است یا خیر. برای محصولات مصرف‌شدنی این رشته می‌تواند کاملاً تصادفی باشد. اما برای محصولات مصرف‌نشدنی یا اشتراکی، برای اطمینان از صحت خریده شدن محصول توسط کاربر باید از رشته‌ای استفاده کنید که منحصراً آن فرد را شناسایی می‌کند.

وقتی‌ که پاسخ را از مایکت دریافت کردید، مطمئن شوید رشتهٔ developer payload که همراه با جزئیات خرید به شما بازگردانده است، همانی است که شما برای شروع عملیات پرداخت ارسال کرده بودید. برای اطمینان از امنیت بیشتر پیشنهاد می‌شود این عملیات اعتبارسنجی را بر روی سِرور خود انجام دهید.

بررسی همیشگی مجوز دسترسی به محتوای برنامه

برای امنیت بیش‌تر پیشنهاد می‌شود که برای محصولات مصرف‌نشدنی و اشتراکی، همیشه با باز شدن برنامه مجوز دسترسی را از مایکت بپرسید و در هیچ‌جا ذخیره نکنید.

تنظیمات ProGuard

در صورتی که از ProGuard برای بهم‌ریختگی و مبهم کردن کد‌های خود استفاده می‌کنید، حتما خط زیر را به تنظیمات ProGuard برنامهٔ خود اضافه کنید:

keep class com.android.vending.billing

تست پیش از انتشار

برای تست سناریو‌های خرید درون‌برنامه‌ای مایکت تنها کافی است که در پنل توسعه‌دهندگان، Packagename برنامهٔ خود را رزرو کنید یا یک نسخه از apk برنامه را بارگذاری نمایید که به کلید رمز عمومی برنامهٔ خود دسترسی داشته باشید. سپس یک یا چند محصول درون‌برنامه‌ای جهت تست با قیمت بسیار کم (مثلا ۱۰۰ ریال) ایجاد کنید و سناریوهای مختلف را تست نمایید. در نظر داشته باشید برای تست خرید درون‌برنامه‌ای نیاز به انتشار برنامه یا تایید مدیر ندارید.

Was this article helpful?
Dislike 0
بعدی: پلاگین خرید درون‌برنامه‌ای یونیتی