Inherits From: LiObject
Declared In: VirtualGood.h

Overview

Applicasa's VirtualGood class provides a great amount of flexibility to offer consumable and non-consumable items to application users. VirtualGood items are offered for sale to users via in-game currency, provided by the VirtualCurrency class. Developers can create any kind of virtual item imaginable, organize them into VirtualGoodCategory groups, and deliver them to users in their own custom UI presentations.

While you can and sometimes will interact with VirtualGood items directly, most typical interactions can be handled via the IAP class API.

VirtualGood items are managed exclusively from the Applicasa developer web portal.

Tasks

Querying Virtual Goods

+ getLocalArrayWithQuery:andBlock:
+ getVirtualGoodsOfType:withBlock:
+ getVirtualGoodsOfType:andCategory:withBlock:

Virtual Good Transactions

- buyQuantity:withCurrencyKind:andBlock:
- giveQuantity:withBlock:
- useQuantity:withBlock:

Properties

virtualGoodID

The item's unique ID value.

@property (nonatomic, retain) NSString *virtualGoodID;

Discussion:

This is the instance's unique ID value as recorded in the Applicasa datastore. It is set by the datastore when you create a new VirtualGood item via the Applicasa developer's web console. This property is not editable.

virtualGoodTitle

The item's display title.

@property (nonatomic, retain) NSString *virtualGoodTitle;

Discussion:

An NSString value for the item's title. You'd most often use this value to display the item's name within your app. Can be edited from the web console.

virtualGoodDescription

The item's description.

@property (nonatomic, retain) NSString *virtualGoodDescription;

Discussion:

This property is editable from the web console.

virtualGoodMainCurrency

An int value indicating the item's price in terms of an app's main currency.

@property (nonatomic, assign) int virtualGoodMainCurrency;

Discussion:

This property is editable from the web console.

virtualGoodSecondaryCurrency

An int value indicating the item's price in terms of an app's secondary currency.

@property (nonatomic, assign) int virtualGoodSecondaryCurrency;

Discussion:

This property is editable from the web console.

virtualGoodRelatedVirtualGood

An NSString indicating a related virtual good tied to this item.

@property (nonatomic, retain) NSString *virtualGoodRelatedVirtualGood;

Discussion:

The virtualGoodRelatedVirtualGood property is used in situations where you want to offer a single VirtualGood that represents a collection of other VirtualGood items.

This property is editable from the web console. You'll find this in the Virtual Good edit window, labeled as Add as Pack, where you'll then choose the related virtual item that is part of the pack.

virtualGoodQuantity

An int value indicating the quantity of related items available with a pack item.

@property (nonatomic, assign) int virtualGoodQuantity;

Discussion:

The virtualGoodQuantity property is only used in conjunction with the virtualGoodRelatedVirtualGood property of collection items. This property is editable from the web console. Whenever you create a VirtualGood as a pack of items, you will set the quantity of included items.

virtualGoodMaxForUser

An int value indicating the maximum number of this kind of item a user is allowed to have in inventory.

@property (nonatomic, assign) int virtualGoodMaxForUser;

Discussion:

Allows developers to set managed limits on any virtual items. This property is editable from the web console.

virtualGoodUserInventory

An int value indicating how many of this item is currently held in a user's inventory.

@property (nonatomic, assign) int virtualGoodUserInventory;

Discussion:

This property is not editable directly, but is updated by the Applicasa IAP framework whenever VirtualGood items are bought, given, or used.

virtualGoodImageA

An NSURL indicating the item's main image location.

@property (nonatomic, retain) NSURL *virtualCurrencyImageA;

Discussion:

This property is automatically generated and updated from the web console.

virtualGoodImageB

An NSURL indicating the item's secondary image location.

@property (nonatomic, retain) NSURL *virtualGoodImageB;

Discussion:

This property is automatically generated and updated from the web console.

virtualGoodImageC

An NSURL indicating the item's tertiary image location.

@property (nonatomic, retain) NSURL *virtualGoodImageC;

Discussion:

This property is automatically generated and updated from the web console.

virtualGoodIsDeal

A BOOL value indicating if the item is a special deal.

@property (nonatomic, assign) BOOL virtualGoodIsDeal;

Discussion:

This property is editable from the web console.

virtualGoodConsumable

A BOOL value indicating if the item is consumable.

@property (nonatomic, assign) BOOL virtualGoodConsumable;

Discussion:

This property is used to indicate whether an item is consumable and should be decremented from user inventory whenever the item is used. If NO, then the item is treated as a non-consumable item that will always be in a user's inventory.

virtualGoodLastUpdate

A datetime value of the last time the item was updated from the web console.

@property (nonatomic, retain, readonly) NSDate *virtualGoodLastUpdate;

Discussion:

This property is automatically generated and updated from the web console.

virtualGoodMainCategory

A VirtualGoodCategory instance indicating to which category this item belongs.

@property (nonatomic, retain) VirtualGoodCategory *virtualGoodMainCategory;

Discussion:

The virtualGoodMainCategory property is set from the web console when managing an item. This property value can be used as an argument to one of the VirtualGood query methods that allow filtering items by category.

Class Methods

getLocalArrayWithQuery:andBlock:

Instructs Applicasa to perform a local-only search for the provided query.

+ (void) getLocalArrayWithQuery:(LiQuery *)query andBlock:(GetVirtualGoodArrayFinished)block;

Parameters:

query
An LiQuery instance that describes a query you wish to perform.

block
A block for handling method completion that must match the signature (NSError *error, NSArray *array).

Discussion:

Because Applicasa keeps a local sqlite-based database synced with the contents of the remote datastore, and because VirtualGood items can grow over time to be a rather lengthy set of records, Applicasa provides developers a means of forcing a local-only query for a specific set of VirtualGood items. This can be used whenever a developer knows they don't want to make a potentially lengthy network call.

getVirtualGoodsOfType:withBlock:

Instructs Applicasa to query for all available VirtualGood items of the specified VirtualGoodType.

+ (void) getVirtualGoodsOfType:(VirtualGoodType)type withBlock:(GetVirtualGoodArrayFinished)block;

Parameters:

type
A VirtualGoodType enum value indicating which kind of VirtualGood to use for the query. Current allowed values are All, NonInventoryItems, and InventoryItems.

block
A block for handling method completion that must match the signature (NSError *error, NSArray *array).

Discussion:

This method provides developers a convenient way to quickly fetch all available VirtualGood items by specified VirtualGoodType. The VirtualGoodType enum currently provides three available types—all virtual goods (All), only items in a user's inventory (InventoryItems), and only items a user does not have in his or her inventory (NonInventoryItems).

Developers can respond to method completion with a block matching the signature (NSError *error, NSArray *array), where the array argument will contain all VirtualGood items returned.

getVirtualGoodsOfType:andCategory:withBlock:

Instructs Applicasa to query for all available VirtualGood items of the specified VirtualGoodType and VirtualGoodCategory.

+ (void) getVirtualGoodsOfType:(VirtualGoodType)type andCategory:(VirtualGoodCategory *)category withBlock:(GetVirtualCurrencyArrayFinished)block;

Parameters:

type
A VirtualGoodType enum value indicating which kind of VirtualGood to use for the query. Current allowed values are All, NonInventoryItems, and InventoryItems.

category
A VirtualGoodCategory instance indicating which category of VirtualGood to use for the query.

block
A block for handling method completion that must match the signature (NSError *error, NSArray *array).

Discussion:

This method provides developers a convenient way to quickly fetch all available VirtualGood items by specified VirtualGoodType and VirtualGoodCategory. The VirtualGoodType enum currently provides three available types—all virtual goods (All), only items in a user's inventory (InventoryItems), and only items a user does not have in his or her inventory (NonInventoryItems). The available VirtualGoodCategory items are dependent entirely on how a developer chooses to categorize VirtualGood items in the Applicasa developer web console.

Developers can respond to method completion with a block matching the signature (NSError *error, NSArray *array), where the array argument will contain all VirtualGood items returned.

Instance Methods

buyQuantity:withCurrencyKind:andBlock:

Instructs Applicasa to purchase a given VirtualGood item selected by the user, in specific quantity, and using the provided currencyKind.

- (void) buyQuantity:(NSInteger)quantity withCurrencyKind:(LiCurrency)currencyKind andBlock:(LiBlockAction)block;

Parameters:

quantity
The desired quantity of items to purchase.

currencyKind
An LiCurrency enum value indicating which kind of VirtualCurrency to use for the transaction. Current allowed values are MainCurrency and SecondaryCurrency.

block
A block for handling method completion that must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

This method is intended for all VirtualGood purchases a developer may wish to perform on behalf of users, providing them with the current instance in return. Developers may respond to method completion to handle success and failure with the block parameter. This block must match the signature (NSError *error, NSString *itemID, Actions action).

Developers are offered the ability to choose which type of currency to use via the currencyKind parameter.

giveQuantity:withBlock:

Instructs Applicasa to give a VirtualGood item to the user, in specific quantity.

- (void) giveQuantity:(NSInteger)quantity withBlock:(LiBlockAction)block;

Parameters:

quantity
The desired quantity of items to give the user.

block
A block for handling method completion that must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

This method is intended for all VirtualGood gifts and rewards for users, providing them with the current instance in return. Developers may respond to method completion to handle success and failure with the block parameter. This block must match the signature (NSError *error, NSString *itemID, Actions action).

useQuantity:withBlock:

Instructs Applicasa to consume a VirtualGood item from the user's inventory, in specific quantity.

- (void) useQuantity:(NSInteger)quantity withBlock:(LiBlockAction)block;

Parameters:

quantity
The desired quantity of items to deduct from the user's inventory.

block
A block for handling method completion that must match the signature (NSError *error, NSString *itemID, Actions action).

Discussion:

This method is intended for all VirtualGood consumption, providing developers with the convenience of deducting an item from a user's inventory. Developers may respond to method completion to handle success and failure with the block parameter. This block must match the signature (NSError *error, NSString *itemID, Actions action).