Mengaktifkan pembelian add-on yang dapat dikonsumsi

  • Artikel

Artikel ini menunjukkan cara menggunakan metode kelas StoreContext di namespace Windows.Services.Store untuk mengelola pemenuhan add-on yang dapat dikonsumsi pengguna di aplikasi UWP Anda. Gunakan add-on yang dapat dikonsumsi untuk item yang dapat dibeli, digunakan, dan dibeli lagi. Ini sangat berguna untuk hal-hal seperti mata uang dalam game (emas, koin, dll.) yang dapat dibeli dan kemudian digunakan untuk membeli power-up tertentu.

Catatan

Namespace Windows.Services.Store diperkenalkan di Windows 10, versi 1607, dan hanya dapat digunakan dalam proyek yang menargetkan Windows 10 Anniversary Edition (10.0; Bangun 14393) atau rilis yang lebih baru di Visual Studio. Jika aplikasi Anda menargetkan versi Windows 10 yang lebih lama, Anda harus menggunakan namespace Windows.ApplicationModel.Store alih-alih namespace Windows.Services.Store. Untuk informasi selengkapnya, lihat artikel ini.

Gambaran umum add-on yang dapat dikonsumsi

Aplikasi dapat menawarkan dua jenis add-on yang dapat dikonsumsi yang berbeda dalam cara pemenuhan dikelola:

  • Dapat dikonsumsi yang dikelola pengembang. Untuk jenis yang dapat dikonsumsi ini, Anda bertanggung jawab untuk melacak saldo item pengguna yang diwakili add-on, dan untuk melaporkan pembelian add-on seperti yang terpenuhi ke Store setelah pengguna mengonsumsi semua item. Pengguna tidak dapat membeli add-on lagi hingga aplikasi Anda melaporkan pembelian add-on sebelumnya sebagai terpenuhi.

    Misalnya, jika add-on Anda mewakili 100 koin dalam game dan pengguna mengonsumsi 10 koin, aplikasi atau layanan Anda harus mempertahankan saldo baru yang tersisa 90 koin untuk pengguna. Setelah pengguna menggunakan semua 100 koin, aplikasi Anda harus melaporkan add-on sesuai kebutuhan, lalu pengguna dapat membeli add-on 100 koin lagi.

  • Dapat dikonsumsi yang dikelola toko. Untuk jenis yang dapat dikonsumsi ini, Store melacak keseimbangan item pengguna yang diwakili add-on. Saat pengguna menggunakan item apa pun, Anda bertanggung jawab untuk melaporkan item tersebut sebagaimana terpenuhi ke Store, dan Store memperbarui saldo pengguna. Pengguna dapat membeli add-on sebanyak yang mereka inginkan (mereka tidak perlu menggunakan item terlebih dahulu). Aplikasi Anda dapat mengkueri Store untuk saldo saat ini untuk pengguna kapan saja.

    Misalnya, jika add-on Anda mewakili jumlah awal 100 koin dalam game dan pengguna mengonsumsi 50 koin, aplikasi Anda melaporkan ke Store bahwa 50 unit add-on terpenuhi, dan Store memperbarui saldo yang tersisa. Jika pengguna kemudian membeli kembali add-on Anda untuk memperoleh 100 koin lagi, mereka sekarang akan memiliki total 150 koin.

    Catatan

    Konsumsi yang dikelola toko diperkenalkan dalam Windows 10, versi 1607.

Untuk menawarkan add-on yang dapat dikonsumsi kepada pengguna, ikuti proses umum ini:

  1. Mengaktifkan pengguna untuk membeli add-on dari aplikasi Anda.
  2. Ketika pengguna menggunakan add-on (misalnya, mereka menghabiskan koin dalam game), laporkan add-on sesuai yang terpenuhi.

Kapan saja, Anda juga bisa mendapatkan sisa saldo untuk store-managed consumable.

Prasyarat

Contoh-contoh ini memiliki prasyarat berikut:

  • Proyek Visual Studio untuk aplikasi Platform Windows Universal (UWP) yang menargetkan Windows 10 Anniversary Edition (10.0; Bangun 14393) atau rilis yang lebih baru.
  • Anda telah membuat pengiriman aplikasi di Pusat Mitra dan aplikasi ini diterbitkan di Bursa. Anda dapat secara opsional mengonfigurasi aplikasi sehingga tidak dapat ditemukan di Store saat Anda mengujinya. Untuk informasi selengkapnya, lihat panduan pengujian kami.
  • Anda telah membuat add-on yang dapat dikonsumsi untuk aplikasi di Pusat Mitra.

Kode dalam contoh ini mengasumsikan:

  • Kode berjalan dalam konteks Halaman yang berisi ProgressRing bernama workingProgressRing dan TextBlock bernama textBlock. Objek ini digunakan untuk menunjukkan bahwa operasi asinkron terjadi dan untuk menampilkan pesan output, masing-masing.
  • File kode memiliki pernyataan penggunaan untuk namespace Windows.Services.Store .
  • Aplikasi ini adalah aplikasi pengguna tunggal yang hanya berjalan dalam konteks pengguna yang meluncurkan aplikasi. Untuk informasi selengkapnya, lihat Pembelian dan uji coba dalam aplikasi.

Untuk aplikasi sampel lengkap, lihat sampel Store.

Catatan

Jika Anda memiliki aplikasi desktop yang menggunakan Desktop Bridge, Anda mungkin perlu menambahkan kode tambahan yang tidak ditampilkan dalam contoh ini untuk mengonfigurasi objek StoreContext . Untuk informasi selengkapnya, lihat Menggunakan kelas StoreContext di aplikasi desktop yang menggunakan Desktop Bridge.

Laporkan add-on yang dapat dikonsumsi sebagai terpenuhi

Setelah pengguna membeli add-on dari aplikasi Anda dan mereka menggunakan add-on Anda, aplikasi Anda harus melaporkan add-on seperti yang dipenuhi dengan memanggil metode ReportConsumableFulfillmentAsync dari kelas StoreContext . Anda harus meneruskan informasi berikut ke metode ini:

  • ID Penyimpanan add-on yang ingin Anda laporkan sebagai terpenuhi.
  • Unit add-on yang ingin Anda laporkan sebagai terpenuhi.
    • Untuk yang dapat digunakan yang dikelola pengembang, tentukan 1 untuk parameter kuantitas . Ini memperingatkan Store bahwa konsumsi telah terpenuhi, dan pelanggan kemudian dapat membeli kembali yang dapat dikonsumsi. Pengguna tidak dapat membeli kembali yang dapat dikonsumsi sampai aplikasi Anda memberi tahu Store bahwa itu terpenuhi.
    • Untuk Store-managed consumable, tentukan jumlah unit aktual yang telah digunakan. Store akan memperbarui sisa saldo untuk yang dapat dikonsumsi.
  • ID pelacakan untuk pemenuhan. Ini adalah GUID yang disediakan pengembang yang mengidentifikasi transaksi tertentu yang dikaitkan dengan operasi pemenuhan untuk tujuan pelacakan. Untuk informasi selengkapnya, lihat keterangan di ReportConsumableFulfillmentAsync.

Contoh ini menunjukkan cara melaporkan store-managed consumable as fulfilled.

private StoreContext context = null;

public async void ConsumeAddOn(string addOnStoreId)
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    // This is an example for a Store-managed consumable, where you specify the actual number
    // of units that you want to report as consumed so the Store can update the remaining
    // balance. For a developer-managed consumable where you maintain the balance, specify 1
    // to just report the add-on as fulfilled to the Store.
    uint quantity = 10;
    Guid trackingId = Guid.NewGuid();

    workingProgressRing.IsActive = true;
    StoreConsumableResult result = await context.ReportConsumableFulfillmentAsync(
        addOnStoreId, quantity, trackingId);
    workingProgressRing.IsActive = false;

    // Capture the error message for the operation, if any.
    string extendedError = string.Empty;
    if (result.ExtendedError != null)
    {
        extendedError = result.ExtendedError.Message;
    }

    switch (result.Status)
    {
        case StoreConsumableStatus.Succeeded:
            textBlock.Text = "The fulfillment was successful. " + 
                $"Remaining balance: {result.BalanceRemaining}";
            break;

        case StoreConsumableStatus.InsufficentQuantity:
            textBlock.Text = "The fulfillment was unsuccessful because the remaining " +
                $"balance is insufficient. Remaining balance: {result.BalanceRemaining}";
            break;

        case StoreConsumableStatus.NetworkError:
            textBlock.Text = "The fulfillment was unsuccessful due to a network error. " +
                "ExtendedError: " + extendedError;
            break;

        case StoreConsumableStatus.ServerError:
            textBlock.Text = "The fulfillment was unsuccessful due to a server error. " +
                "ExtendedError: " + extendedError;
            break;

        default:
            textBlock.Text = "The fulfillment was unsuccessful due to an unknown error. " +
                "ExtendedError: " + extendedError;
            break;
    }
}

Dapatkan sisa saldo untuk konsumsi yang dikelola Toko

Contoh ini menunjukkan cara menggunakan metode GetConsumableBalanceRemainingAsync dari kelas StoreContext untuk mendapatkan saldo yang tersisa untuk add-on yang dapat dikonsumsi yang dikelola Store.

private StoreContext context = null;

public async void GetRemainingBalance(string addOnStoreId)
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    workingProgressRing.IsActive = true;
    StoreConsumableResult result = await context.GetConsumableBalanceRemainingAsync(addOnStoreId);
    workingProgressRing.IsActive = false;

    // Capture the error message for the operation, if any.
    string extendedError = string.Empty;
    if (result.ExtendedError != null)
    {
        extendedError = result.ExtendedError.Message;
    }

    switch (result.Status)
    {
        case StoreConsumableStatus.Succeeded:
            textBlock.Text = "Remaining balance: " + result.BalanceRemaining;
            break;

        case StoreConsumableStatus.NetworkError:
            textBlock.Text = "Could not retrieve balance due to a network error. " +
                "ExtendedError: " + extendedError;
            break;

        case StoreConsumableStatus.ServerError:
            textBlock.Text = "Could not retrieve balance due to a server error. " +
                "ExtendedError: " + extendedError;
            break;

        default:
            textBlock.Text = "Could not retrieve balance due to an unknown error. " +
                "ExtendedError: " + extendedError;
            break;
    }
}