A product is an individual item for sale in a merchant's store. Products can be physical goods, servics or digital downloads.

When working with products it is important to undertand what a product variant is. A variant is an individual style or type of a product. For example, a t-shirt may be available with different choices for size and colour. Each valid combination of optoins for these two attributes will be a variant of the t-shirt product (i.e. Large White t-shirt, Small Red t-shirt).
If a product only has one style or type, then it is considered to be a single variant.

This page covers:


Retrieving a Product

Retrieve the product from the PTKProductWorkflow. (see triggers and workflows for how to get the workflow).

The workflow also contains a possible set of coupons that the user can redeem on this or future purchases. The coupons are automatically saved to the user's profile but returned here so they can be displayed to the user.

PTKProduct *product = workflow.product;
NSArray<PTKCoupon> *coupons = workflow.triggeredCoupons;
// Display coupons to user.

Checking if a Product has Multiple Variants

If a product has multiple variants it will have options that the user must choose from in order to identify which variant they want. A single variant product will not have any option choices.

Check to see whether the product has option choices:

if ([product hasOptionChoices]) {
	// Need to provide functionality to the user to select a variant
} else {
	// The product only has a single variant
	PTKProductVariant *selectedVariant = [product.variants objectAtIndex:0];
}

Selecting a Product Variant

The product options must be displayed to the user so they can choose a single product variant, but not all options are valid in combination with one another. For example, the merchant might not sell a 'Large Pink t-shirt' but they do sell a 'Small Pink t-Shirt'

To simply this process, a ProductVariantPicker is provided that you can bind to your UI to help users choose one option at a time until a valid combination of options has been chosen, resulting in a single variant.
For each choice (e.g. size or color) there are a number of options (e.g. Red and Blue options for color) and each option has a state indicating whether it is currently chosen and whether it can be chosen based on the currently chosen options.


  1. If the product has multiple variants, create a PTKProductVariantPicker and get the choices for the product:

Use the PTKProductVariantPicker to get a list of PTKProductOptionChoice, one for each available choice (e.g. Size, Color). Each PTKProductOptionChoice contains a list of PTKProductOptionState objects which is a wrapper for the PTKProductOption to provide state information like whether it is currently chosen or available for selection.

PTKProductVariantPicker *picker = [PTKProductVariantPicker productVariantPickerWithProduct:product];
NSArray *optionChoices = picker.optionChoices;
// Display the choices in some manner
[self displayChoices:optionChoices];

  1. To choose a specific option call the pickers chooseOption method:

This will update the state of the options in the choices list based on the currently chosen options. The list is updated in-place so there is no need to get the list from the picker again.

NSArray *chosenOptions = [picker chooseOption:productOption];
[self displayChoices:optionChoices];

  1. To find out what the currently chosen options are:

Like the list of option choices, when changes are made this list is updated in-place:

NSArray *chosenOptions = picker.chosenOptions;

  1. You can find out which variants match the current option choices:
NSArray *variants = [picker variants];

Once a desired option has been selected for each choice, the number of variants returned will either be 1 (the desired variant) or 0 (no variants available that match the current selection).


  1. To deselect an already chosen option:

To un-choose an option:

[picker unchooseOption:option];
[self displayChoices:optionChoices];

To clear all chosen options:

[picker reset];
[self displayChoices:optionChoices];

Checking if User Has Picked a Variant

To determine if a variant has been selected, you need to check if the user has selected an option for every choice.
The isOptionChosenForEveryChoice method returns 'true' once a single variant has been chosen:

[picker isOptionChosenForEveryChoice];

Useful Product Methods

  1. The following methods can be used to obtian useful product information:
// Get the ID of the product.
NSString *productId = product.productId;

// Get the ID of the merchant which this product is from.
NSString *merchantId = product.merchantId;

// Get The Global Trade Item Number (GTIN) that uniquely identifies the product globally, if it has one.
NSString *gtin = product.gtin;

// Get the product title
NSString *title = product.title;

// Get the product description.
NSString *productDescription = product.productDescription;

// Get the brand associated with the product.
NSString *brand = product.brand;

// Get the product condition. e.g. new, refurbished, used or unknown
PTKProductCondition condition = product.condition;

// Get a URL to view more information about the product. The URL is optional
NSURL *productLink = product.link;

// Get the list of categories this product is in.
NSArray *categories = product.categories;

Next Step: Adding a Product Variant to a Basket

Add the product variant to the users basket in preparation for check out.


Sample

To explore this topic in detail, import the sample app and review the ProductController class.