پولکی

پولکی چیست؟

«پولکی» کتابخانه‌ای نو برای پیاده‌سازی پرداخت درون برنامه بازار است که با زبان برنامه نویسی Kotlin توسعه داده شده و از چارچوب ReactiveX پشتیبانی می‌کند. هدف از پیاده‌سازی این کتابخانه، بهبود فرآیند پیاده‌سازی پرداخت درون برنامه ای بازار برای توسعه دهندگان بازار است.

---

استفاده از پولکی

۱: افزودن کتابخانه به پروژه

برای شروع، کتابخانه پولکی را به پروژه خود در فایل build.gradle اضافه کنید:

dependencies {
    implementation "com.github.cafebazaar.Poolakey:poolakey:[latest_version]"
}

 سپس باید jitpack را به فایل build.gradle  اضافه کنید:

repositories {
        google()
        jcenter()
        maven { url 'https://jitpack.io' }
    }

 مطمئن شوید که از آخرین نسخه پولکی استفاده می‌کنید:

https://github.com/PHELAT/Poolakey/releases

۲: ساخت و ساز

ساختار پرداخت درون برنامه‌ ای به شکلی‌ای است که برنامه شما باید مستقیما با برنامه بازار صحبت کند تا بتواند عملیات خرید و مواردی از این دست را انجام دهد. برای صحبت کردن با بازار ابتدا باید به بازار متصل شوید. برای انجام این کار، وارد فایل Activity یا  Fragment خود شوید و در متد onCreate یک نمونه از کلاس SecurityCheck درست کنید:

val localSecurityCheck = SecurityCheck.Enable(
  rsaPublicKey = "KEY"
)

به جای مقدار KEY باید از کلید برنامه خود استفاده کنید، برای دریافت کلید برنامه به پنل پیشخان مراجعه کنید و در صفحه اطلاعات برنامه، وارد تب «پرداخت درون برنامه ای» شوید و کلید را از آنجا کپی کنید و به جای مقدار KEY در نمونه کد بالا قرار دهید.

در مرحله بعد باید یک نمونه از کلاس PaymentConfiguration درست کنید و localSecurityCheck را به آن تزریق کنید:

val paymentConfiguration = PaymentConfiguration(
  localSecurityCheck = localSecurityCheck
)

و در آخرین مرحله باید یک نمونه از کلاس Payment درست کنید:

val payment = Payment(context = this, config = paymentConfiguration)

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

۳. اتصال به بازار

برای اتصال به بازار، باید از فانکشن connect موجود در کلاس Payment استفاده کنید:

val paymentConnection = payment.connect {
  connectionSucceed {
        ...
  }
  connectionFailed { throwable ->
        ...
  }
  disconnected {
        ...
  }
}

در بدنه فانکشن connect به سه callback دسترسی دارید:

• connectionSucceed وقتی صدا زده می‌شود که اتصال به بازار برقرار شود
• connectionFailed وقتی صدا زده می‌شود که اتصال به بازار برقرار نشود
• disconnected وقتی صدا زده می‌شود که طبق رویدادی ارتباط برنامه شما با بازار قطع شود

همان‌طور که می‌بینید، در connectionFailed به یک نمونه از throwable دسترسی دارید که به کمک آن می‌توان متوجه مشکلی که باعث عدم اتصال برنامه شما به بازار شده است شد.

۴: قطع اتصال با بازار

برای جلوگیری از مشکلاتی همچون Memory Leak باید در متد onDestroy از Activity یا Fragment خود، اقدام به قطع اتصال با بازار کنید:

override fun onDestroy() {
  paymentConnection.disconnect()
  super.onDestroy()
}

۵. شروع روند خرید یک محصول

برای شروع روند خرید یک محصول، باید ابتدا یک نمونه از کلاس PurchaseRequest ساخته شود:

val purchaseRequest = PurchaseRequest(
   productId = "PRODUCT_ID",
   payload = "PAYLOAD"
)

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

سپس با استفاده از فانکشن purchaseProduct از کلاس Payment روند خرید محصول مورد نظر را شروع کنید:

payment.purchaseProduct(
  registry = activityResultRegistry,
  request = purchaseRequest
) {
  purchaseFlowBegan {
        ...    
  }
  failedToBeginFlow { throwable ->
        ...    
  }
  purchaseSucceed { purchaseEntity ->
        ...
  }
  purchaseCanceled {
        ...       
  }
  purchaseFailed { throwable ->
        ...        
  }
}

در بدنه فانکشن purchaseProduct به  callback های زیر دسترسی دارید:

• purchaseFlowBegan وقتی صدا زده می‌شود که فرایند هدایت کاربر به صفحه خرید بازار به درستی انجام شود.
• failedToBeginFlow وقتی صدا زده می‌شود که فرایند هدایت کاربر به صفحه خرید بازار به درستی انجام نشود.

همانطور که می‌بینید، در failedToBeginFlow به یک نمونه از throwable دسترسی دارید که به کمک آن می‌توان متوجه مشکلی که در شروع فرایند خرید شده است شد.

• purchaseSucceed وقتی صدا زده می‌شود که خرید با موفقیت انجام شود، که در این صورت از طریق purchaseEntity می‌توانید به اطلاعات خرید دست پیدا کنید. توجه کنید که در صورت موفقیت‌آمیز بودن خرید، بسیار پیشنهاد می‌شود که از طریق API پرداخت بازار، خودتان صحت پرداخت را نیز بررسی کنید.
• purchaseCanceled وقتی صدا زده می‌شود که کاربر از خرید منصرف شود.
• purchaseFailed وقتی صدا زده می‌شود که مشکلی در خرید وجود داشته باشد. این مشکل می‌تواند از جنس صحت نداشتن اطلاعات خرید و مشکلات مشابه باشد. در این‌صورت به کمک نمونه throwable موجود در این callback می‌توانید از اشکال به‌وجود آمده مطلع شوید.

۶: شروع روند اشتراک یک محصول

برای اشتراک یک محصول، دقیقا مثل شروع خرید یک محصول عمل کنید و به جای استفاده از فانکشن purchaseProduct از فانکشن subscribeProduct موجود در کلاس Payment استفاده کنید.

۷: مصرف کردن خرید کاربر

وقتی کاربر یکی از محصولات دیجیتالی برنامه شما را خریداری می‌کند، مالک یک نسخه محصول مورد نظر می‌شود و در صورتی که شما کاربر را مجددا به صفحه پرداخت هدایت کنید، کاربر نمی‌تواند دوباره خرید خود را انجام دهد و با اطلاعات خرید قبلی به برنامه شما باز می‌گردد (purchaseSucceed). اما شما می‌توانید برای محصول مورد نظر خود تاریخ مصرف و یا شرایط خاصی را در نظر بگیرید تا خرید مصرف شود. در این صورت کاربر می‌تواند مجددا خرید خود را انجام دهد. برای مصرف کردن یک خرید از فانکشن consumeProduct موجود در کلاس Payment استفاده کنید:

payment.consumeProduct("PURCHASE_TOKEN") {
  consumeSucceed {
      ...
  }
  consumeFailed { throwable ->
      ...
  }
}

همان‌طور که می‌بینید، در بدنه consumeProduct به دو callback دسترسی دارید:

• consumeSucceed وقتی صدا زده می‌شود که عملیات مصرف کردن خرید با موفقیت انجام شود.
• consumeFailed وقتی صدا زده می‌شود که عملیات مصرف کردن خرید انجام نشود، در این شرایط شما می‌توانید با استفاده از نمونه throwable موجود در این callback متوجه مشکل موجود شوید.

توجه کنید به‌جای مقدار PURCHASE_TOKEN در نمونه کد بالا، باید مقدار واقعی توکن خریدی که می‌خواهید مصرف شود را قرار دهید. دسترسی به توکن خرید، از طریق کلاس PurchaseEntity امکان‌پذیر است. وقتی کاربر خرید انجام می‌دهد، پولکی به شما یک PurchaseEntity در purchaseSucceed می‌دهد. همچنین می‌توانید تمام خریدهای کاربر که در برنامه شما انجام داده است را از طریق فانکشن getPurchasedProducts بدست بیاورید که در این صورت، پولکی به شما لیستی از  PurchaseEntity می‌دهد که از این طریق نیز می‌توان به توکن خرید دسترسی پیدا کرد.

توجه: محصولات اشتراکی را نمی‌توانید مصرف کنید.

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

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

شما می‌توانید با استفاده از فانکشن getPurchasedProducts موجود در کلاس Payment از خریدهای کاربر که در برنامه شما انجام داده است، مطلع شوید:

payment.getPurchasedProducts {
  querySucceed { purchasedProducts ->
      ...
  }
  queryFailed { throwable ->
      ...
  }
}

همانطور که می‌بینید، در بدنه getPurchasedProducts به دو callback دسترسی دارید:

• querySucceed وقتی صدا زده می‌شود که ارتباط با بازار به خوبی برقرار شود و مشکلی در دریافت لیست خریدها وجود نداشته باشد. در این صورت، با استفاده از purchasedProducts که لیستی از PurchaseInfo است می‌توانید به خریدهای کاربر دسترسی پیدا کنید.
• queryFailed وقتی صدا زده می‌شود که ارتباط با بازار برقرار نشود یا مشکلی در دریافت لیست خریدها وجود داشته باشد. در این صورت، می‌توانید با استفاده از نمونه throwable موجود در این callback متوجه مشکل به‌وجود آمده شوید.

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

۹: دریافت اشتراک‌های کاربر در برنامه شما

شما می‌توانید با استفاده از فانکشن getSubscribedProducts موجود در کلاس Payment از محصولاتی که کاربر اشتراک آن‌ها را در برنامه شما خریداری کرده، مطلع شوید:

payment.getSubscribedProducts {
  querySucceed { purchasedProducts ->
      ...
  }
  queryFailed { throwable ->
      ...
  }
}

همانطور که می‌بینید، در بدنه getSubscribedProducts به دو callback دسترسی دارید:

• querySucceed وقتی صدا زده می‌شود که ارتباط با بازار به خوبی برقرار شود و مشکلی در دریافت لیست اشتراک‌ها وجود نداشته باشد که در این صورت، با استفاده از purchasedProducts که لیستی از PurchaseInfo است می‌توانید به اشتراک‌های کاربر دسترسی پیدا کنید.
• queryFailed وقتی صدا زده می‌شود که ارتباط با بازار برقرار نشود یا مشکلی در دریافت لیست اشتراک‌ها وجود داشته باشد، که در این شرایط، می‌توانید با استفاده از نمونه throwable موجود در این callback متوجه مشکل به‌وجود آمده شوید.

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

۱۰: بررسی وضعیت اشتراک آزمایشی برای کاربر

شما می‌توانید با استفاده از فانکشن checkTrialSubscription موجود در کلاس Payment از وضعیت امکان تعلق اشتراک آزمایشی به کاربر ‌در برنامه خود مطلع شوید:

payment.checkTrialSubscription {
    checkTrialSubscriptionSucceed { trialSubscriptionInfo ->

     }

     checkTrialSubscriptionFailed { throwable ->

     }
  }

همان‌طور که می‌بینید، در بدنه checkTrialSubscription به دو callback دسترسی خواهید داشت:

• checkTrialSubscriptionSucceed وقتی صدا زده می‌شود که ارتباط با بازار به خوبی برقرار شود و مشکلی در دریافت وضعیت اشتراک آزمایشی وجود نداشته باشد که در این صورت، با استفاده از trialSubscriptionInfo می‌توانید به وضعیت امکان تعلق اشتراک آزمایش کاربر دسترسی پیدا کنید.trialSubscriptionInfo شامل فیلدهای زیر است:
•  isAvailable: (که در صورتی که فعال باشد true و در غیر این صورت false خواهد بود)، این فیلد در صورت فعال بودن نشانگر این است که در صورت خرید اشتراک توسط کاربر، اشتراک آزمایشی بجای اشتراک خریداری شده برای او فعال خواهد شد و پس از اتمام اشتراک آزمایشی با اشتراک اول تمدید خواهد شد.
• trialPeriodDays: طول اشتراک آزمایشی که به کاربر تعلق خواهد گرفت.
• checkTrialSubscriptionFailed وقتی صدا زده می‌شود که ارتباط با بازار برقرار نشود یا مشکلی در دریافت وضعیت اشتراک آزمایشی وجود داشته باشد، که در این شرایط، می‌توانید با استفاده از نمونه throwable موجود در این Callback، متوجه مشکل به‌وجود آمده شوید.

نکات مهم: قبل از کار با checkTrialSubscription باید مطمئن شوید که کاربر وارد حساب بازار خود شده است، در غیر این‌صورت checkTrialSubscriptionFailed صدا زده می‌شود. برای بررسی وضعیت اشتراک کاربر پس از فعال‌سازی اشتراک آزمایشی می‌توانید از قسمت «دریافت اشتراک‌های کاربر در برنامه شما» استفاده کنید.

پرداخت با یونیتی

با استفاده از دستور زیر می‌توانید از پلاگین پرداخت درون برنامه یونیتی برای پولکی استفاده کنید.

var connectionResult = await payment.Connect();
var purchaseResult = await payment.Purchase("productID");
var consumeResult = await payment.Consume(purchaseResult.data.purchaseToken);

توجه: کتابخانه پولکی برای پروژه‌های یونیتی 2020 و بالاتر قابل اجرا می‌باشد.

بیشتر بخوانید:

• خطای نصب در پیشخان بازار چگونه کار می‌کند؟
• راهنمای پیشخان
• معرفی پرداخت