PlayerIO

The fastest way to build online games without breaking a sweat.

Objective-C Client Reference

Class PIOPayVault

Language: Objective-C

The Player.IO PayVault.

Instances of this class represent a specific user's Vault, and contains methods and properties both for inspecting and manipulating the contents.

All properties and methods that inspect the Vault requires that it is up-to-date first. This can be achieved explicitly by calling the -refresh: method or implicitly by calling any method which modifies the Vault.

Here is how to read the Coins balance:

This is how you check if an item exists:

Credit and Debit can be used like this:

Buying items with Coins is really easy. This example requires that you have created an item in the PayVaultItems table in BigDB with the key "speedboost", and a property "PriceCoins" containing the price.

And here's how to consume an item:

When it's time for a user to add more Coins, you can do it like this:

And this is how to let the user buy an item directly. This requires that you have created an item in the PayVaultItems table in BigDB with the key "supercar", and a property "PriceUSD" containing the price.

Finally, there are methods for retrieving the payment history of a user:

Methods

- (void)

buyItems:storeItems:successBlock:

Buy items with Coins.

- (void)

buyItems:storeItems:successBlock:errorBlock:

Buy items with Coins.

- (long)

coins

Get the current coin balance in this Vault. This method can only be called on an up-to-date vault.

- (void)

consumeItem:successBlock:

Consume an item in the Vault. This will cause the item to be removed. The action will not show up in the vault history.

- (void)

consumeItem:successBlock:errorBlock:

Consume an item in the Vault. This will cause the item to be removed. The action will not show up in the vault history.

- (void)

consumeItems:successBlock:

Consume items in this Vault. This will cause them to be removed. The action will not show up in the vault history.

- (void)

consumeItems:successBlock:errorBlock:

Consume items in this Vault. This will cause them to be removed. The action will not show up in the vault history.

- (NSUInteger)

countOfItem:

Returns the number of items of a given itemKey is in this Vault. This method can only be called on an up-to-date vault.

- (void)

creditCoins:reason:successBlock:

Give coins to this Vault

- (void)

creditCoins:reason:successBlock:errorBlock:

Give coins to this Vault

- (void)

debitCoins:reason:successBlock:

Take coins from this Vault

- (void)

debitCoins:reason:successBlock:errorBlock:

Take coins from this Vault

- (PIOVaultItem*)

firstItem:

Returns the first item of the given itemKey from this Vault. This method can only be called on an up-to-date vault.

- (void)

getBuyCoinsInfoWithProvider:purchaseArguments:successBlock:

Gets information about how to make a coin purchase with the specified PayVault provider.

- (void)

getBuyCoinsInfoWithProvider:purchaseArguments:successBlock:errorBlock:

Gets information about how to make a coin purchase with the specified PayVault provider.

- (void)

getBuyDirectInfoWithProvider:purchaseArguments:items:successBlock:

Gets information about how to make a direct item purchase with the specified PayVault provider.

- (void)

getBuyDirectInfoWithProvider:purchaseArguments:items:successBlock:errorBlock:

Gets information about how to make a direct item purchase with the specified PayVault provider.

- (void)

giveItems:successBlock:

Give the user items without taking any of his coins from the vault.

- (void)

giveItems:successBlock:errorBlock:

Give the user items without taking any of his coins from the vault.

- (BOOL)

hasItem:

This method checks if the Vault contains at least one item of the given itemKey. This method can only be called on an up-to-date vault.

- (NSArray*)

items

Get the list of items in this Vault. This method can only be called on an up-to-date vault.

- (void)

readHistoryWithPage:pageSize:successBlock:

Loads a page of entries from this Vaults history, in reverse chronological order, i.e. newest first.

- (void)

readHistoryWithPage:pageSize:successBlock:errorBlock:

Loads a page of entries from this Vaults history, in reverse chronological order, i.e. newest first.

- (void)

refreshWithSuccessBlock:

Refreshes this Vault, making sure the Items and Coins are up-to-date.

- (void)

refreshWithSuccessBlock:errorBlock:

Refreshes this Vault, making sure the Items and Coins are up-to-date.

- (void)

useBuyInfoWithProvider:providerArguments:successBlock:

Use information from a provider to finalize a purchase with the specified PayVault provider.

- (void)

useBuyInfoWithProvider:providerArguments:successBlock:errorBlock:

Use information from a provider to finalize a purchase with the specified PayVault provider.

buyItems:storeItems:successBlock:

Buy items with Coins.

Arguments

NSArray*	items
	A list of items to buy, together with any additional payload.
BOOL	storeItems
	Whether or not to store the items in the vault after purchase
void(^)(void)	successBlock
	A callback block that will be called when the item has been successfully bought with coins.

Throws

PlayerIOError

buyItems:storeItems:successBlock:errorBlock:

Buy items with Coins.

Arguments

NSArray*	items
	A list of items to buy, together with any additional payload.
BOOL	storeItems
	Whether or not to store the items in the vault after purchase
void(^)(void)	successBlock
	A callback block that will be called when the item has been successfully bought with coins.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

coins

Get the current coin balance in this Vault. This method can only be called on an up-to-date vault.

Return Value

long

consumeItem:successBlock:

Consume an item in the Vault. This will cause the item to be removed. The action will not show up in the vault history.

Arguments

PIOVaultItem*	item
	The VaultItem to use from the users vault - this should be an instances from the items in this Vault.
void(^)(void)	successBlock
	A callback block that will be called when the item has been removed from the users vault.

Throws

PlayerIOError

consumeItem:successBlock:errorBlock:

Consume an item in the Vault. This will cause the item to be removed. The action will not show up in the vault history.

Arguments

PIOVaultItem*	item
	The VaultItem to use from the users vault - this should be an instances from the items in this Vault.
void(^)(void)	successBlock
	A callback block that will be called when the item has been removed from the users vault.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

consumeItems:successBlock:

Consume items in this Vault. This will cause them to be removed. The action will not show up in the vault history.

Arguments

NSArray*	items
	The VaultItems to use from the users vault - this should be instances of items in this Vault.
void(^)(void)	successBlock
	A callback block that will be called when the items has been removed from the users vault.

Throws

PlayerIOError

consumeItems:successBlock:errorBlock:

Consume items in this Vault. This will cause them to be removed. The action will not show up in the vault history.

Arguments

NSArray*	items
	The VaultItems to use from the users vault - this should be instances of items in this Vault.
void(^)(void)	successBlock
	A callback block that will be called when the items has been removed from the users vault.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

countOfItem:

Returns the number of items of a given itemKey is in this Vault. This method can only be called on an up-to-date vault.

Arguments

NSString*	itemKey
	The itemKey of the items to count.

Return Value

NSUInteger

The number of items of the given type that the user has in the vault.

Throws

PlayerIOError

creditCoins:reason:successBlock:

Give coins to this Vault

Arguments

NSUInteger	coinAmount
	The amount of coins to give.
NSString*	reason
	Your reason for giving the coins to this user. This will show up in the vault history, and in the PayVault admin panel for this user.
void(^)(void)	successBlock
	A callback block that will be called when the coins have been credited to the vault.

Throws

PlayerIOError

creditCoins:reason:successBlock:errorBlock:

Give coins to this Vault

Arguments

NSUInteger	coinAmount
	The amount of coins to give.
NSString*	reason
	Your reason for giving the coins to this user. This will show up in the vault history, and in the PayVault admin panel for this user.
void(^)(void)	successBlock
	A callback block that will be called when the coins have been credited to the vault.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

debitCoins:reason:successBlock:

Take coins from this Vault

Arguments

NSUInteger	coinAmount
	The amount of coins to take.
NSString*	reason
	Your reason for taking the coins from this user. This will show up in the vault history, and in the PayVault admin panel for this user.
void(^)(void)	successBlock
	A callback block that will be called when the coins have been debited from the vault.

debitCoins:reason:successBlock:errorBlock:

Take coins from this Vault

Arguments

NSUInteger	coinAmount
	The amount of coins to take.
NSString*	reason
	Your reason for taking the coins from this user. This will show up in the vault history, and in the PayVault admin panel for this user.
void(^)(void)	successBlock
	A callback block that will be called when the coins have been debited from the vault.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

firstItem:

Returns the first item of the given itemKey from this Vault. This method can only be called on an up-to-date vault.

Arguments

NSString*	itemKey
	The itemKey of the item to get.

Return Value

PIOVaultItem*

A VaultItem if one was found, or null if not.

Throws

PlayerIOError

getBuyCoinsInfoWithProvider:purchaseArguments:successBlock:

Gets information about how to make a coin purchase with the specified PayVault provider.

Arguments

NSString*	provider
	The name of the PayVault provider to use for the coin purchase.
NSDictionary*	purchaseArguments
	Any additional information that will be given to the PayVault provider to configure this purchase.
void(^)(NSDictionary*)	successBlock
	A callback block that will be called with information about how to complete the coins purchase.

Throws

PlayerIOError

getBuyCoinsInfoWithProvider:purchaseArguments:successBlock:errorBlock:

Gets information about how to make a coin purchase with the specified PayVault provider.

Arguments

NSString*	provider
	The name of the PayVault provider to use for the coin purchase.
NSDictionary*	purchaseArguments
	Any additional information that will be given to the PayVault provider to configure this purchase.
void(^)(NSDictionary*)	successBlock
	A callback block that will be called with information about how to complete the coins purchase.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

getBuyDirectInfoWithProvider:purchaseArguments:items:successBlock:

Gets information about how to make a direct item purchase with the specified PayVault provider.

Arguments

NSString*	provider
	The name of the PayVault provider to use for the item purchase.
NSDictionary*	purchaseArguments
	Any additional information that will be given to the PayVault provider to configure this purchase.
NSArray*	items
	A list of items to buy, together with any additional payload.
void(^)(NSDictionary*)	successBlock
	A callback block that will be called with information about how to complete the buy item direct purchase.

Throws

PlayerIOError

getBuyDirectInfoWithProvider:purchaseArguments:items:successBlock:errorBlock:

Gets information about how to make a direct item purchase with the specified PayVault provider.

Arguments

NSString*	provider
	The name of the PayVault provider to use for the item purchase.
NSDictionary*	purchaseArguments
	Any additional information that will be given to the PayVault provider to configure this purchase.
NSArray*	items
	A list of items to buy, together with any additional payload.
void(^)(NSDictionary*)	successBlock
	A callback block that will be called with information about how to complete the buy item direct purchase.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

giveItems:successBlock:

Give the user items without taking any of his coins from the vault.

Arguments

NSArray*	items
	A list of items to give, together with any additional payload.
void(^)(void)	successBlock
	A callback block that will be called when the item is succesfully given.

Throws

PlayerIOError

giveItems:successBlock:errorBlock:

Give the user items without taking any of his coins from the vault.

Arguments

NSArray*	items
	A list of items to give, together with any additional payload.
void(^)(void)	successBlock
	A callback block that will be called when the item is succesfully given.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

hasItem:

This method checks if the Vault contains at least one item of the given itemKey. This method can only be called on an up-to-date vault.

Arguments

NSString*	itemKey
	The itemKey to check for.

Return Value

BOOL	True if the user has at least one item of the given type (itemKey).

Throws

PlayerIOError

items

Get the list of items in this Vault. This method can only be called on an up-to-date vault.

Return Value

NSArray*

readHistoryWithPage:pageSize:successBlock:

Loads a page of entries from this Vaults history, in reverse chronological order, i.e. newest first.

Arguments

NSUInteger	page
	The page of entries to load. The first page has number 0.
NSUInteger	pageSize
	The number of entries per page.
void(^)(NSArray*historyEntries)	successBlock
	A callback block that will be called with the history entries in the specified page.

Throws

PlayerIOError

readHistoryWithPage:pageSize:successBlock:errorBlock:

Loads a page of entries from this Vaults history, in reverse chronological order, i.e. newest first.

Arguments

NSUInteger	page
	The page of entries to load. The first page has number 0.
NSUInteger	pageSize
	The number of entries per page.
void(^)(NSArray*historyEntries)	successBlock
	A callback block that will be called with the history entries in the specified page.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

refreshWithSuccessBlock:

Refreshes this Vault, making sure the Items and Coins are up-to-date.

Arguments

void(^)(void)	successBlock
	A callback block that will be called when the vault is successfully updated.

Throws

PlayerIOError

refreshWithSuccessBlock:errorBlock:

Refreshes this Vault, making sure the Items and Coins are up-to-date.

Arguments

void(^)(void)	successBlock
	A callback block that will be called when the vault is successfully updated.
void(^)(PIOError*error)	errorBlock
	A callback block that will be called on error, with information about the error.

useBuyInfoWithProvider:providerArguments:successBlock:

Use information from a provider to finalize a purchase with the specified PayVault provider.

Arguments

NSString*	provider
	The name of the PayVault provider to use for the purchase.
NSDictionary*	providerArguments
	The information needed to finalize this purchase.
void(^)(NSDictionary*)	successBlock
	The callback that will be used to return results. On success its successBlock method will be called, otherwise its onError method.

useBuyInfoWithProvider:providerArguments:successBlock:errorBlock:

Use information from a provider to finalize a purchase with the specified PayVault provider.

Arguments

NSString*	provider
	The name of the PayVault provider to use for the purchase.
NSDictionary*	providerArguments
	The information needed to finalize this purchase.
void(^)(NSDictionary*)	successBlock
	The callback that will be used to return results. On success its successBlock method will be called, otherwise its onError method.
void(^)(PIOError*error)	errorBlock
	The callback that will be called on error with information about the error.