Usage

Below outlines various usage patterns.

Assume the following for simplicity:

Owner ID: 0000

User ID: 0001

License: my-game

License: another-game

Purchase virtual currency using real money

An item definition that defines a gold virtual currency

{
    "item_id": "0000:gold",
    "item_name": "Gold",
    "item_desc": "Gold",
    "item_type": "currency",
    "item_owner": "0000",
    "creator_license": ["my-game"]
}

A product definition that gives user 10 Gold for $0.99 CAD.

{
    "product_id": "bag_of_gold",
    "product_name": "Bag of gold",
    "product_desc": "Bag of gold",
    "product_type": "real",
    "cost": [{ "cost_type": "real#CAD", "quantity": 0.99 }],
    "items": [
        { "item_id": "0000:gold", "quantity": 10 }
    ],
    "product_owner": "0000",
    "license": "my-game"
}

Once user makes a purchase of the above product, this is added to user inventory. User can make additional purchase to the same product, and the item is added to the same entry in inventory, incrementing the quantity.

{
    "inventory_key": {
        "user_id": "0001",
        "item_type": "currency",
        "item_id": "0000:gold"
    },
    "inventory_item": <copy of the item def>,
    "quantity": 10
}

Purchase in-game item using virtual currency

Continuing from the above example...

An item definition that defines a sword

{
    "item_id": "0000:sword",
    "item_name": "Sword",
    "item_desc": "Sword",
    "item_type": "equipment",
    "item_owner": "0000",
    "creator_license": ["my-game"]
}

A product definition that gives user a Sword for 5 Gold. Virtual product essentially exchange some quantity of items in user inventory for some other items.

{
    "product_id": "Sword",
    "product_name": "Sword",
    "product_desc": "Sword",
    "product_type": "virtual",
    "cost": [{ "cost_type": "0000:gold", "quantity": 5 }],
    "items": [
        { "item_id": "0000:sword", "quantity": 1 }
    ],
    "product_owner": "0000",
    "license": "my-game"
}

Once user makes a purchase of the above product, Sword is added to the user inventory and 5 Gold is deducted.

{
    "inventory_key": {
        "user_id": "0001",
        "item_type": "currency",
        "item_id": "0000:gold"
    },
    "inventory_item": <copy of the item def>,
    "quantity": 5
},
{
    "inventory_key": {
        "user_id": "0001",
        "item_type": "equipment",
        "item_id": "0000:sword"
    },
    "inventory_item": <copy of the item def>,
    "quantity": 1
}

Purchase store subscription

Items purchased through a real product can be tied to the Google PlayStore / Apple AppStore subscription.

An item definition that defines a premium membership

{
    "item_id": "0000:premium",
    "item_name": "premium",
    "item_desc": "premium",
    "item_type": "membership",
    "item_owner": "0000",
    "creator_license": ["my-game"]
}

A product definition that gives user the premium membership. Note that the item is flag with is_subscription. There is no need to define expiry, it is set according to store subscription's expiry. A subscription item is always unique in the user inventory, not aggregated with items of same ID (unlike the gold example)

{
    "product_id": "premium",
    "product_name": "premium membership",
    "product_desc": "premium membership",
    "product_type": "real",
    "cost": [{ "cost_type": "real#CAD", "quantity": 0.99 }],
    "items": [
        { "item_id": "0000:premium", "quantity": 1 , "is_subscription": true }
    ],
    "product_owner": "0000",
    "license": "my-game"
}

Items can be given out to user each time a user re-subscribe in the store (ie. enter a new billing period). Modifying the previous example, this product gives user premium membership and 10 gold on initial purchase. When the subscription renews in the store, the user will receive another 10 gold. This continues each time the subscription renews until subscription is cancel in the store.

{
    "product_id": "premium",
    "product_name": "premium membership",
    "product_desc": "premium membership",
    "product_type": "real",
    "cost": [{ "cost_type": "real#CAD", "quantity": 0.99 }],
    "items": [
        { "item_id": "0000:premium", "quantity": 1 , "is_subscription": true },
        { "item_id": "0000:gold", "quantity": 10 , "add_on_resubscribe": true }
    ],
    "product_owner": "0000",
    "license": "my-game"
}

Purchase item as unique items

By default, items given out in product are aggregated. That is, stacked into one entry in user inventory with the quantity increment by each purchase.

For items that are subscription or with specific expiry, they are non-aggregated because they have unique properties that need to distinguish from other items of same ID.

Items can also be marked as unique explicitly by using the is_unique flag as shown below.

{
    "product_id": "sword",
    "product_name": "sword",
    "product_desc": "sword",
    "product_type": "real",
    "cost": [{ "cost_type": "real#CAD", "quantity": 0.99 }],
    "items": [
        { "item_id": "0000:sword", "quantity": 1 , "is_unique": true }
    ],
    "product_owner": "0000",
    "license": "my-game"
}

After user purchase the above product twice, inventory will have two entries of sword:

{
   "inventory_key": {
       "user_id": "0001",
       "item_type": "equipment",
       "item_id": "0000:sword",
       // inventory key has transac_id and item_index because it's unique entry
       "transac_id": "000001",
       "item_index": "0"
    },
    "inventory_item": <copy of the item def>,
    quantity: 1
},
{
   "inventory_key": {
       "user_id": "0001",
       "item_type": "equipment",
       "item_id": "0000:sword",
       // inventory key has transac_id and item_index because it's unique entry
       "transac_id": "000002",
       "item_index": "0"
    },
    "inventory_item": <copy of the item def>,
    quantity: 1
}

Give reward to user

Only the game owner, such as the actor, can give out reward.

Reward product has no cost.

This reward gives user 100 Gold.

{
    "product_id": "complete_level1",
    "product_name": "Reward for complete level 1",
    "product_desc": "Receives 100 Gold",
    "product_type": "reward",
    "items": [
        { "item_id": "0000:gold", "quantity": 100 }
    ],
    "product_owner": "0000",
    "license": "my-game"
}

Product not allowed to create item

Below is product from another game. This product definition can be created but when user tries to purchase this product, inventory service will return error. The reason is because another-game is not in the creator_license array in 0000:gold item definition.

{
    "product_id": "bag_of_gold",
    "product_name": "Bag of gold",
    "product_desc": "Bag of gold",
    "product_type": "real",
    "cost": [{ "cost_type": "real#CAD", "quantity": 0.99 }],
    "items": [
        { "item_id": "0000:gold", "quantity": 10 }
    ],
    "product_owner": "0000",
    "license": "another-game"
}

The same error will occur in this example, because another-game cannot consume 0000:gold for the same reason. It also cannot create 0000:sword

{
    "product_id": "Sword",
    "product_name": "Sword",
    "product_desc": "Sword",
    "product_type": "virtual",
    "cost": [{ "cost_type": "0000:gold", "quantity": 5 }],
    "items": [
        { "item_id": "0000:sword", "quantity": 1 }
    ],
    "product_owner": "0000",
    "license": "another-game"
}