The Bidco SDK 'Act' functionality provides your app users with a means to respond to a merchant's call to action.

Some examples of Acts:

  • Book a test drive at a car dealership.
  • Request an information pack from a charity.
  • Enter a competition.

When a merchant creates an 'Act' they specify the information they require from the user which is then stored as a template on the server and linked to an PTKActWorkflow.
When a user interacts with a Bidco trigger that results in an PTKActWorkflow, the user needs to be prompted to provide the information required.


The following sections are covered:


Retrieving the Act Details


  1. Get the Act from the workflow:
PTKAct *act = workflow.act;

  1. Get the Act fields to display to the user:
// Get the Act ID
NSString *actId = act.actId;

// Get the Act name
NSString *actName = act.name;

// get the Act headline
NSString *headline = act.headline;

// Get the merchant's message for the Act
NSString *message = act.message;

// Get the Terms & Conditions to display for this Act
NSString *terms = act.termsAndConditions;

// Get any images to display
NSArray<PTKActImage> *images = act.images;

// Get the merchant's thank you message for displaying after the act has been transmitted
NSString *thankYouMessage = act.thankYouMessage;

  1. Get the Act data keys:

The data needed to display the custom field to the user is stored in PTKActDataKey

for (PTKActDataKey actDataKey : act.actDataKeys) {
	// Retrieve the key identifier for this custom value
	NSString *key = actDataKey.key;

	// Retrieve the display name of the custom value
	NSString *name = actDataKey.name;

	// Retrieve the data type the must be returned to the SDK. valid types are String, Time, Date, Email, Address, boolean
	PTKActDataType actDataType = actDataKey.type;

	// Retrieve the optional options list items and display to the user
	if(actDataType == PTKActDataTypeOptionsList){
		NSARRAY<NSString> optionsListItems = actDataKey.optionsListItems;
	}
	
	// Retrieve the optional predefined value to display to the user
	NSString *value = actDataKey.predefinedValue;

	// Retrieve the flag indicating if this is an optional field
	BOOL optional = actDataKey.optional;
}

Preparing the Act Transaction Details

The user's response must be stored in an PTKActTransactionDetails so that it can be submitted to the server.

PTKActTransactionDetails *actTransactionDetails = [PTKActTransactionDetails actTransactionDetails];

Adding an Act Data Value


Add the values supplied by the user for each PTKActDataKey:

// Add the user's value as a string
[actTransactionDetails addActDataValueForKey:actDataKey value:userValueString];

Note: At the very least, add the user values for all mandatory keys.


Removing an Act Data Value


  1. To remove a stored user value:
BOOL valueRemoved = [actTransactionDetails removeActDataValue:actDatakey];

Removing All Act Data Values


  1. To clear PTKActTransactionDetails of all act data values:
actTransactionDetails.clearActDataValues();

Obtaining All Act Data Values

  1. To obtain all act data values added to ActTransActionDetails:
NSDictionary *actDataValues = [actTransactionDetails actDataValues];

Submit the Act Transaction Details


Submit the act transaction details to the Bidco server using the PTKActManager.
An 'PTKActTransaction' is returned that contains:

  • The transaction Id that can be used to retrieve the transaction details.
  • A set of coupons that the user can redeem on future purchases. The coupons are automatically saved to the user's profile but returned here so they can be displayed to the user.
PTKActManager *actManager = [PTKActManager sharedManager];
// submit the transaction and keep the transaction ID stored in actTransaction
[actManager submitTransactionWithAct:act transactionDetails:actTransactionDetails completion:^(PTKActTransaction *actTransaction, NSError *error){
	// Keep transaction Id for retrieving transaction history
	NSString transactionId = actTransaction.transactionId;
	
	// Display returned coupons to user	
	NSArray<PTKCoupon> coupons = actTransaction.triggeredCoupons;
	
}];