QuickPrints SDK for ios Version 3.3 August 06, 2014

Size: px

Start display at page:

Download "QuickPrints SDK for ios Version 3.3 August 06, 2014"

Gwendolyn Burke
6 years ago
Views:

1 Introduction The QuickPrints SDK for ios (ipod Touch, iphone, and ipad) is a static library that provides a set of APIs that can be used to submit a photo print order to a Walgreens store. This document gives step-bystep directions on how to integrate the QuickPrints SDK into an ios application. Typographical conventions Classes, methods, variables, field names, and parameter names shall be appear in a fixed-width font Blocks of code will appear in gray boxes with a fixed-width font o Text with a yellow highlight within a block of code are to be replaced with what the text describes; i.e. if affiliate ID is highlighted, then replace that text with an affiliate ID Red colored text should always be read carefully Prerequisites The following items are required in order to use the Walgreens QuickPrints SDK for ios: be utilizing ios 6.0 or higher be developing an application for the United States o QuickPrints is only available via Walgreens, which currently does not have any stores outside of the United States and Puerto Rico have a user account on the Walgreens Developer Portal have an API key have an Affiliate ID have a unique Publisher ID, in order to earn a revenue share commission on photo orders submitted to and sold by Walgreens ensure that all image files to be printed exist in, or be converted to JPEG (.jpg) format prior to being uploaded to Walgreens (or referenced via URL) Instructions on how to get a user account, API key, Affiliate ID, and Publisher ID are listed below Walgreen Co. All Rights Reserved. Page 1

2 Registering with Walgreens To setup a developer account with Walgreens and obtain the API key and Affiliate ID, developers must: create a user account on the Walgreens Developer Portal ( sign into the Walgreens Developer Portal ( select the Set Up an Application button (in the My Page tab) and fill out the form (to request an API key) Once the application has been approved by Walgreens, an automated will be generated and sent to the requester with a link to view the requester's unique API key. The automated will also include a generic test Affiliate ID, extest1. The requester's unique Affiliate ID will be provided to the developer once the requester's application is ready to commence onboard testing with the Walgreens Developer Program team. Registering with Commission Junction Walgreens has partnered with Commission Junction to handle revenue sharing. In order to earn a revenue share commission from photo orders submitted to and sold by Walgreens, a Publisher ID (PID) is required. To obtain a unique Publisher ID: go to click on the Apply link at the top of the page fill out and submit the application form log back in to the portal, once the application has been approved o An automated will be generated and sent to the requester review and accept the Walgreens Photo-Finishing Services Agreement proceed into the "Account" section of the Account Profile to obtain your Website ID (PID) number 2014 Walgreen Co. All Rights Reserved. Page 2

3 How to use the QuickPrints SDK 1. Add the following files into the project: libquickprintsdk.a, WAG_CheckoutContext.h, and WAG_ImageData.h. In addition, the project will also need to link to the following frameworks: AssetsLibrary CoreLocation SystemConfiguration CoreImage QuickPrints ios SDK v3.1 and up contains support for armv7s, which was introduced in io6 2. Import the following headers whenever functions from the SDK will be used: #import WAG_CheckoutContext.h #import WAG_ImageData.h 3. Make sure that the class implements the CheckoutDelegate ViewController: UIViewController <CheckoutDelegate> 2014 Walgreen Co. All Rights Reserved. Page 3

4 4. Create an instance of WAG_CheckoutContext and initialize it WAG_CheckoutContext *checkoutsdk = [[WAG_CheckoutContext alloc] initwithaffliateid: Affiliate ID apikey: API Key environment: 0 appversion: Application Version ProductGroupID: Product Group ID PublisherID: Publisher ID]; All parameters are strings with the exception of environment, which is an integer Set environment to: 0 to use the staging servers 1 to use the production servers Refer to Prerequisites (on page 1) on how to get the Affiliate ID, API Key, and Publisher ID Unless explicitly instructed by Walgreens, ProductGroupID should be an empty string (@"") If revenue is not be collected, set PublisherID to an empty string (@"") Example Code snippet: checkoutsdk = [[WAG_CheckoutContext alloc] initwithaffliateid:@"vendor" apikey:@"dsj3hgd3khdidkd" environment:0 appversion:@"2.0" ProductGroupID:@"ProductGroupID0001" PublisherID:@"111111"]; Delegate methods for Authentication: // On successful authentication -(void) initsuccessresponse:(nsstring *)response; // On failure authentication -(void) didinitfailwitherror:(nserror *)error; // On service exception -(void) didservicefailwitherror:(nserror *)error; 5. (Optional, but highly recommended) To pass customer information to the SDK for pre-population within Order Checkout -(void)setuserinfowith:(nsstring *)firstname LastName:(NSString *)lastname (NSString *) PhoneNo:(NSString *)phoneno; Any combination of these customer information fields can be passed to the SDK. For unused parameters, use Null. 6. (Optional) To pass a coupon code to the SDK for pre-population within Order Checkout -(void)setcouponcode:(nsstring*)couponcode; 2014 Walgreen Co. All Rights Reserved. Page 4

5 7. Pass device information to the SDK so the correct checkout URL is given -(void)setdevicetype:(nsstring *)devtype; devtype should be a string with the following syntax: device +, + OS version number o for device, use iphone for any iphone ipad for any ipad, including the ipad Mini ipod for any ipod Touch o e.g. iphone,6.1.4 or ipad, Uploading images to Walgreens and/or use a public URL // (Optional, not recommended for photos) Disable image compression -(void)disableimagecompression:(bool)isdisabled; // Upload an image to Walgreens -(void) upload:(id)arg; (OR) // Use the below method for Uploading images For Creative Products to Walgreens. Refer Notes below for CREATIVE PRODUCTS -(void) upload:(id )arg filename:(id)filename // Add a public image URL to the image queue -(void) addimageurl:(nsstring*)imageurl; // To get the maximum number of images that can be added to the image queue, which // includes both images uploaded and public image URLs -(NSInteger) getmaximumimageuploadcount; // To get the current number of images (both uploaded and URLs) in the image queue -(NSInteger) uploadedimagecount; By default, all images are automatically compressed before they are uploaded Ideally, images with a pixel per inch (PPI) density over 300 that will be printed on an 8x10 print or smaller should be scaled down to at least 300 PPI before uploading Image are automatically compressed using: UIImageJPEGRepresentation(image, 0.7) Compression at that rate will have no visible effects on images with a PPI of 300 (and up) for 8x10 and smaller prints Compression can be disabled, but this is only recommended for canvas, posters, and other larger prints The argument can be either a NSData or NSArray object If a NSData object is used, convert the UIImage to NSData before uploading If a NSArray object is used, an array of ALAsset objects with a count no greater than 5 must be used A maximum of 5 images can be uploaded in a single batch Additional images or batches for upload cannot be added, until a submitted batch completes (with either success or failure) 2014 Walgreen Co. All Rights Reserved. Page 5

6 The maximum number of images that can be uploaded in a single transaction (regardless of batch count) is 100 An error shall be returned if the image uploaded was not a JPG file For visual optimization on ipad implementations, please present the Walgreens Landing Page in a modal sized no larger than 540 pixels wide by 620 pixels high. Creative Products [Calendars, Books & Folded Cards] When uploading images for the Creative Products, below method should be used with strict adherence to the File Naming conventions -(void) upload:(id )arg filename:(id)filename a. If NSArray is passed as first argument, then the second argument should be an array of filenames of type NSString b. If NSData is passed as first argument, then the second argument should be a filename of type NSString c. The File Name for Creative Products should start with a prefix of P***_ where *** represents the order of the image uploaded, which in turn, the final product have the images printed in the same sequence. For example, if the image with File Name Walgreens.JPG is uploaded as the 1 st image, then the File Name should be passed as P001_Walgreens.JPG. Similarly for 10 th Image, the File Name should be passed as P010_<<ImageNameWithExtension>>. If for some reasons, if the above said convention is not followed, the images may not be printed in the same order as it was uploaded Walgreen Co. All Rights Reserved. Page 6

7 Delegate methods for uploading images: // Successful image upload -(void) imageuploadsuccesswithimagedata:(wag_imagedata *)imagedata; // Failure response for image upload -(void) imageuploaderrorwithimagedata:(wag_imagedata *)imagedata Error:(NSError *)error; // Get the upload progress every time data is sent -(void) getuploadprogress:(float)progress; // Batch upload is completed -(void) didfinishbatch; WAG_ImageData is defined WAG_ImageData : NSObject { NSString *uploadstate; // State of the uploading image UIImage *imgsource; // If the image is of NSData, the value will be // set to nil once it is uploaded, due to a // memory issue ALAsset *imgasset; // Local image reference NSString *imagekey; // ID associated with this image batch NSString *filename; // Filename of the image data. 9. Images can be deleted/removed from the order using the SDK APIs as follows: // Remove an image that is already uploaded -(void) removeimagefromqueuewithasset:(alasset *)asset; // Remove one image URL from the order -(void) removeimagefromqueuewithurl:(nsstring *)imgurl; // Remove all images in upload image queue -(void) clearimagequeue; // Canceling the whole batch -(void) cancelimageupload; Warning: There is currently no method to remove a specific set of image URLs; if an image URL needs to be removed, clearimagequeue needs to be called 2014 Walgreen Co. All Rights Reserved. Page 7

8 10. After all images have been uploaded, use the postcart method to start the checkout process // If additional notes need to be sent to Walgreens, include the notes with: -(void) setaffnotes:(nsstring*)affnotes; // Call this method once the uploading process is complete, and the user is ready // to move on to the checkout process -(void) postcart; // to check if an image upload is still in progress, call: +(BOOL) inprogress; setaffnotes: must only be called if the Walgreens team advises it If setaffnotes: is going to be called, it must be called before the postcart method The NSString that is passed into setaffnotes: must not exceed 240 characters Delegate methods for the postcart method: // postcart() was successful -(void) cartpostersuccessresponse:(nsstring *)response; // postcart() failed -(void) didcartpostfailwitherror:(nserror *)error; The response parameter from cartpostersuccessresponse will have the URL for the check out process; load this URL in a UIWebView to begin the check out process. 11. To start the check out process, load the URL via a UIWebView handler. Implement the following code in a web view controller // Assuming that the following was called at one point: // CGRect screenframe = [[UIScreen mainscreen] applicationframe]; // UIWebView *awebview = [[UIWebView alloc] initwithframe:screenframe]; for (id subview in awebview.subviews) { if ([[subview class] issubclassofclass: [UIScrollView class]]){ ((UIScrollView *)subview).bounces = NO; ((UIScrollView *)subview).scrollenabled = NO; [awebview setdelegate:self]; [awebview loadrequest:[nsurlrequest requestwithurl:[nsurl URLWithString:cartPostURL]]]; cartposturl is a NSString with a value equal to response from cartpostersuccessresponse Make sure the web view is non-scrollable 2014 Walgreen Co. All Rights Reserved. Page 8

9 In order to override the web view, call shouldstartloadwithrequest method for handling the Javascript: -(BOOL)webView:(UIWebView *)webview shouldstartloadwithrequest:(nsurlrequest *)request navigationtype:(uiwebviewnavigationtype)navigationtype { if ([self String:[[request URL] absolutestring] Contains:@"QP_BACK:"] [self String:[[request URL] absolutestring] Contains:@"QP_ERROR:"] [self String:[[request URL] absolutestring] Contains:@"QP_DONE:DONE"] [self String:[[request URL] absolutestring] Contains:@"QP_CANCEL:"]) { [self dismisscontroller]; return NO; -(void)dismisscontroller { [awebview stoploading]; [self.navigationcontroller dismissmodalviewcontrolleranimated:yes]; -(BOOL)String:(NSString *)astring Contains:(NSString *)asubstring { NSRange range = [astring rangeofstring:asubstring options:nscaseinsensitivesearch]; if(range.location!= NSNotFound) { return YES; return NO; 2014 Walgreen Co. All Rights Reserved. Page 9

10 SDK Related Error Codes & Error Handling Error Code Constant Name Description 901 ERR_CODE_JSON_EXCEPTION Invalid JSON format received from server. 902 ERR_CODE_SIGNATURE_EXCEPTION Error in encrypting API key. Invalid Signature. Please contact Walgreens. 903 ERR_CODE_EXCEED_UPLOAD_IMAGE_COUNT_LIMIT Maximum upload limit count reached. 904 ERR_CODE_ALREADY_INITIALIZED SDK is already initialized. 905 ERR_CODE_NOT_INITIALIZED SDK is not Initialized. 906 ERR_INITIALIZATION Problem when initialize the SDK. 907 ERR_CODE_FILE_ALREADY_UPLOADED Image already uploaded to server. 908 ERR_CODE_UPLOAD_CANCELED Upload cancelled. 909 ERR_CODE_UPLOAD_FAILED Upload failed. 910 ERR_CODE_HTTP_CONNECTION Server unavailable. 911 ERR_CODE_EMPTY_CART No file in the cart. 912 ERR_CODE_INVALID_API_KEY Invalid API Key. 913 ERR_CODE_AFFILIATE_ID Invalid Affiliate ID. 914 ERR_CODE_INVALID_ENVIROLMENT Invalid environment argument while initializing SDK. 915 ERR_CODE_INVALID_SEVER_URL Invalid Server URL. 916 ERR_CODE_INVALID_IMAGE Invalid image file/no image available. 917 ERR_CODE_EMPTY_FILE Empty image file. 918 ERR_CODE_ILLEGAL_STATE Illegal SDK state. Upload is already in progress. 919 ERR_CODE_EXCEED_BATCH_IMAGE_COUNT Number of images in a batch exceeded the current limit of ERR_CODE_UNSUPPORTED_IMAGE_FORMAT Unsupported image format. 921 ERR_ CODE_NO_FILES_TO_UPLOAD There is no file to upload. All Images have been uploaded already. 922 ERR_ CODE_START_UPLOAD_SERVICE Problem starting the background image upload service. 923 ERR_ CODE_NULL_ANDROID_CONTEXT Android Context is null. It must be valid android context. 924 ERR_CODE_NETWORK_UNAVAILABLE SDK unable to connect to the Internet/network due to a weak or unavailable signal Walgreen Co. All Rights Reserved. Page 10

11 HTML5 Related Error Codes & Error Handling Error Code Constant Name Description 652 STORE_NOTAVAILABLE No stores found. 654 PRICE_PRODUCT_MISSING Product price is missing. 655 PRICE_EXCEPTION Exception in price. 656 COUPON_MISSING Coupon is missing. 657 COUPON_EXCEPTION Exception in coupon. 658 DEVICEINFO_MISSING Device info missed COUPON_INVALID Coupon invalid. Please enter a valid coupon CART_EXPIRED Cart (Session) has expired. Please try again SERVICE_UNAVAILABLE The service is temporarily unavailable. Please try again later AFFILIATE_NOTEXIST Invalid affiliate INVALID_SIGNATURE Invalid Signature NOT_AUTHORIZED Not Authorized INVALID_QUANTITY Invalid quantity. Please enter a valid quantity INVALID_PRICE Invalid Quantity. Unmentioned Methods The following methods are listed in the header files, but not mentioned above: Method -(NSString*) getsdkversioninfo; -(void) setpreferredstore:(nsstring*)prestore_; -(id) initwithaffliateid:(nsstring*)affidstr apikey:(nsstring*)apikey environment:(nsinteger)envtype appversion:(nsstring*)version; -(id) initwithaffliateid:( NSString*)affIdStr apikey:(nsstring*)apikey serviceurl:(nsstring*)urlstr environment:(nsinteger)envtype appversion:(nsstring*)version; Description Returns the version of the SDK; this is for internal helper method Sets the preferred Walgreens store; do NOT use this this is for internal testing purposes only Alternative method to initialize WAG_CheckoutContext; do NOT use this or else orders will not generate a revenue share Alternative method to initialize WAG_CheckoutContext; do NOT use this this is for internal testing purposes only 2014 Walgreen Co. All Rights Reserved. Page 11

Introduction. Typographical conventions. Prerequisites. QuickPrints SDK for Windows 8 Version 1.0 August 06, 2014

Introduction. Typographical conventions. Prerequisites. QuickPrints SDK for Windows 8 Version 1.0 August 06, 2014 Introduction The QuickPrints SDK for Windows 8 provides a set of APIs that can be used to submit a photo print order to a Walgreens store. This document gives step-by-step directions on how to integrate