Wix Art Store Provider

This article will guide through on how to build & integrate a provider for the Art Store. The Provider should let the user set prices on its products in the Wix Site Editor and sell the user's art online.

Note: Only pre-approved providers may integrate with the Art Store. For more details, contact us at [email protected].

Getting started

Do the following steps twice: 1 for a production environment and one for local development.

1. Go to Wix Dev Center and create a new app for the provider.
2. In the app's editing page, add 6 Widget-type compoentns with the following Component names: shop pricing manage cart thankyou and checkout. Each endpoint will be presented on a different part of the Art Store.
3. Install the wix-art-store-3rd-party in the project npm install --save wix-art-store-3rd-party
4. Include the store sdk in each of the endpoints (Mandatory):

var storeSdk = require('wix-art-store-3rd-party/dist/src/sdk');

or

import storeSdk from 'wix-art-store-3rd-party/dist/src/sdk';

Important: The sdk must be loaded on each endpoint in order to interact with the art store.

• Send us the App Id and App Secret in order to register the provider in our Art Store server.

Endpoints

As mentioned before, the app should have the following component names configured: shop pricing manage cart thankyou and checkout. Every endpoint will receive the following parameters:

• pInstance: A parameter signed with the App's secret key according to the Wix Platform Style. The value of the parsed parameter is a JSON containing the following properties:

  • instanceId: Click here for details.
  • signDate: When was the pInstance signed.
  • siteOwnerId: Id of the site's owner
  • uid: The id of the wix user viewing the site (will be empty if the viewer is not a wix user). This parameter can be used to check if the current user is the owner by doing: siteOwnerId === uid
  • ipAndPort

• locale: e.g. en/fr etc..

• deviceType: desktop / mobile

• cachekiller

• token: used by the SDK for internal functionality

Endpoints and SDK in detail:

The Sdk exposes a Json object in the following format:

{
    shop:{/* methods for the shop endpoint */},
    cart:{/* methods for the cart endpoint */},
    checkout:{/* methods for the checkout endpoint */},
    pricing:{/* methods for the pricing endpoint */},
    manage:{/* methods for the manage endpoint */},
    thankyou:{/* methods for the thankyou endpoint */},
    
    modal:{/* methods for handling a modal which can be opened in some locations */},
    getStyles: {/* A method that returns the styles of the site */}
}

shop

Will appear in the Art Store's expand mode page. This is where the site's visitor chooses and customizes the product. This endpoint will receive additional parameters on the url:

• itemId: Should be ignored for now
• itemHeight: px height
• itemWidth
• itemType: image/video/text - Currently, only image is supported
• imageUrl: Although saying url in the parameter, this is not the url for the image but will be used to get the full res image without the watermark from the Art Store's server when a purchase is made.
• originalUrl: Full url for the image
• itemUrl: Will be used to acquire the full res image from the server

The shop should always display a default product with default customizations and be prepared to receive an "add to cart" command (via the SDK)

SDK mthods:

• openModal(name, options) : Promise<void>: In the expand mode, there's an option to open a modal over the page that allows advanced editing of the product.

  • name: In order to open a modal, another Component (Widget) should be defined in the App in the dev center. The name parameter must match the 'Component Name' in the dev center.
  • options: object:
    • urlParams: object: key value pair of additional url parameters sent to the modal endpoint
    • urlPath: string: additional url path to add to the url for example: '/item/1'

• addToCart(itemDetails: object, metadata: object, options: object) : Promise<void>: This method should be used when the user wants to add the current item to the cart.

  • itemDetails: Not used for now and will be removed soon.
  • metadata: object: A place for storing the user's choices about the product. For example: 'selectedLicenseId'. Note: This object should only hold IDs and not raw data, the size is limited.
  • options
    • quantity(optional): number: Must be positive. Default: 1
    • uuid(optional): string

• setHeight(height: number): void: To avoid double scrollers, we need the provider to tell us the entire height of the application's frame so we can adjust it accordingly.

• checkout(options: object): Call this method to go to the checkout page.

  • options: Pass additional parameters/path to get them in the checkout endpoint
    • additionalParams: object: key value pair
    • additionalPath: string

• onItemChanged(callback: function): void: The callback will get invoked when the user flips through the images with the new image's details.

  • callback: Will receive an obkect with the same parameters mentioned above (itemId, itemHeight etc..)

• onAddToCart(callback: function): void: The callback is invoked when the user can wants to checkout from outside of the frame. In general, the addToCart method should be called directly.

• setDefaultPrice(data: object): void: For mobile TBD

cart

Visible globally on the right side of the site and shared with all Art Stores in the site. Note: All cart items are stored and managed by the SDK.

SDK mthods:

• openModal(name, options) : Promise<void>: See shop.openModal
• onRefreshCart(callback: function): Will be called when something changes in the cart (add/remove).
  • callback(items: array<cartItem>): Will receive the current state of the cart
    • cartItem: object: Properties
      • galleryId: string: The id of the gallery from which this item was added to the cart
      • isDemo: boolean: The user may add demo images to the cart - these items cannot be sold.
      • metadata: object: Object supplied when adding to cart
      • providerId: The App Id
      • quantity: number
      • uuid: string: An Id for this item. Use this ID later to update or remove an item from the cart
• getSiteInfo(): Promise<siteInfo: object>: Use this method to get some info about the hosting site - mainly used to get relevant urls so the app will navigate to (like after a purchase)
  • siteInfo: Will contain the following info:
    • checkoutUrl: Url for the checkout page
    • thankYouUrl
    • siteUrl: base url of the site
    • url: the current url
    • dashboardUrl: (not available in all enpoints)
• checkout(options: object): See shop.checkout
• removeItem(uuid: string): void
• onCheckout(callback: function): void: User requests to checkout. The checkout method should be called directly.
• updateitem(uuid: string, options: object): void
  • options: object
    • metadata(optional): object: New metadata for the item.
    • quantity(optional): number
• clearCart(): void

checkout

The checkout endpoint will load on the entire screen once requested. When navigating from the SDK, this endpoint will receive the additionalUrl and path params.

SDK mthods:

• home(options: object): void: Use this methos to navigate back home
  • options: object
    • openCart: boolean: set to true to open the cart when the home page is loaded
• getSiteInfo(): Promise<siteInfo: object>: See cart.getSiteInfo

pricing

Opens from the Art Store in the Wix Editor. Pricing page is where the user defines the prices and customizations on a specific Art Store.

SDK mthods:

• close(): void: Close the pricing window
• getSiteInfo(): Promise<siteInfo: object>: See cart.getSiteInfo
• openFile(): Promise<fileData: object>: If the selling items require the user to upload a file (like a license agreement), use this method to get a link to that file.
  • fileData: object
    • url: string
    • fileName: string
  • manage(): void: Open the manage endpoint

manage

This endpoint can be opened from either the Wix Editor or Wix Back Office. This endpoint is in charge of the global site settings like Business info and payment methods

SDK mthods:

• gotoPricing(): void: Open the pricing page (only if the manage window was opened from the editor)
• close(): void: Close the window
• openFile(): Promise<fileData: object>: See pricing.openFile()
• openMedia() : Promise<mediaUrl: string>: An option to get a media url from the user. (For example: business logo url)

thankyou

This endpoint should be navigated to once a purchase is complete. This is not a full screen page so, just like in the shop endpoint, the height of the endpoint should be set to prevent multiple scrollers. All parameters added to the thankyou url will be automatically passed through to the provider's frame.

SDK mthods:

• setHeight(height: number): void: See shop.setHeight
• home(options: object): void: See checkout.home

[modal]

This endpoint can be opened from both shop and cart endpoints. This endpoint should be configured in the Wix Dev Center and opened by Component Name. It only loads per request from the SDK

SDK mthods:

• close(): void: Close the modal
• addToCart(itemDetails: object, metadata: object, options: object) : Promise<void>:
• removeItem(uuid: string): void
• updateitem(uuid: string, options: object): void
• getCartItems(options: object): Promise<items: array<cartItem>>: A method to get items from the cart
  • options:
    • uuid(optional): string: A specific item's uuid to get only that item in the response. (not supplying this parameter will return all items)

Styling

The provider should be styled according to the Wix styling rules of the site. The SDK will provide the necessary colors and fonts that the site uses in order to make the provider a seemless part of the site.

SDK mthods:

• getStyles(): Proimise<styles: object>

In addition to the getStyles method the, SDK will automatically create css and add it to the DOM. TBD

Get full res images with no watermark

The images in the Art Store may be embedded with a watermark and resolution may be reduced. For the provider to get the full/original image(s) they need to make a POST request to the Art Store's server containg the details of the purchase. The requst is sent to https://progallery.wix.com/api/v1/providers/[App Id]/secure-download (Insert the provider's App Id)

The request's payload should be a JSON with the following format:

 { signedDownloadInstance: signedPayload }

(Content type header must be set: 'Content-Type': 'application/json')

The signedPayload should be signed by the provider according to the wix format. Sample payload:

{
  "appDefId": "[Provider's AppId from the dev center]",// mandatory
  "instanceId": "[From request pInstance]",// mandatory
  "signedAt": "2017-07-20T12:47:02.275Z",// mandatory // new Date().toISOString()
  "userId": "[uid or anonymousUserId from the request]",// mandatory
  "userIp": "[From request pInstance - called ipAndPort]",// mandatory
  "ownerId": "[From request pInstance]",// mandatory
  "transactionId": "[The id of the purchase for later reference]",// mandatory
  "buyerName": "[Name of the buyer]",// mandatory
  "currency": "[USD, EUR, GBP etc..]",// mandatory
  "items": [{ // mandatory - Must be at least one item to purchase
    "galleryId": "[Will be available with each cart item]",// mandatory
    "mediaUrl": "[This is the 'itemUrl' of an item example: weQ6XWAmuN6a8Ta4YKUYEche2rb3Ip4A.jpg]",// mandatory
    "category": "[Digital / Print]",// mandatory
    "product": "[License / Mugs / Canvas etc...]",// mandatory
    "price": 10, // mandatory - Price of each item
    "dimensions": { // Not mandatory! This will scale down the image if needed to fit the dimentsion
      "width": 1200, // In px - Mandatory if 'dimensions' attribute exists
      "height": 1200 // In px - Mandatory if 'dimensions' attribute exists
    }
  }],
  "expiresIn": 50 // mandatory - Integer representing minutes. When that time exipres, the received URL will no longer be available.
}

The response data is a JSON in the following format:

"urls": [
    "/secure-files/[image 1]",
    "/secure-files/[image 2]"
  ]
}

Each item is a URL for the same index that was sent in the reqest. (Each url should be prepended with 'http://files.wix.com')

Testing the provider

Once the provider is approved and the AppId and App Secret are registered on the Art Store's server the provider should then be available testing. To do that Follow these steps:

1. Create a new site
2. Add the 'Wix Art Store' from the app market.
3. Open Art Store's settings
4. Open dev tools and select the settings' window
5. Run this command in the console: window.WixStoreApi.connectProvider('[AppId here]')
6. If everything went OK, the provider should be connected to that Art Store.
7. Good Luck! :boom: