Wix::Apps

Rack middleware for use with "Third Party Applications" on the Wix platform. It handles the instance param passed by Wix requests for configurable paths. It checks the signature, parses the contents and passes a convenient Object to your application via env.

Installation

Important note: if you're using a pre-1.0.0-version of this gem, please be aware the API changed significantly. You will have to update some of your code. However, in versions >= 1.0.0 should be a corresponding method for anything from version 0.0.x.

Add this line to your application's Gemfile:

gem 'wix-apps', '~> 1.0.0'

And then execute:

$ bundle

Or install it yourself as:

$ gem install wix-apps

Usage

Any Rack Application

Add Wix::Apps::SignedInstanceMiddleware like any other middleware.

use Wix::Apps::SignedInstanceMiddleware, secret_key: 'secret_key',
  secured_paths: ['/your', '/paths', %r{\A/wix/(auth|update)\z}]

Rails

In application.rb, add:

config.middleware.use Wix::Apps::SignedInstanceMiddleware, secret_key: 'your-secret-key',
  secured_paths: ['/wix']

In your controller handling a configured secured path, access the signed instance:

class WixController < ApplicationController
    def index
        # retrieve Wix::Apps::SignedInstance object
        instance = request.env['wix.instance']
        
        if instance.owner_permissions? 
        ...

env['wix.instance']

This WixApps middleware passes on a Wix::Apps::SignedInstance object through env['wix.instance']. The object has the following methods:

Object method	Type	Description
instance_id	String	Required Wix instance property `instanceId`
sign_date	DateTime	Required Wix instance property `signDate`
uid	String	Optional Wix instance property `uid`
permissions	String	Required Wix instance property `permissions`
ip_and_port	String	Required Wix instance property `ipAndPort`
vendor_product_id	String	Required Wix instance property `vendorProductId`
aid	String	Required Wix instance property `aid`
origin_instance_id	String	Optional Wix instance property `originInstanceId`
site_owner_id	String	Required Wix instance property `siteOwnerId`
owner_permissions?	Boolean	Indicates if instance user has owner (includes site administrators) permissions
owner_logged_in?	Boolean	Indicates if instance user is the single owner of the site

Options

secured_paths

An Array of String- and Regexp-objects describing the paths to be secured by checking the Wix signed instance. On request, the path will be checked against every entry in this list. Strings are checked for equality, Regexps are matched (without additional conditions, so use \A and \z for start and end markers if you need them!). Keep in mind rack's paths always begin with a '/'.

Example (secures '/auth_path', every path containing the string 'wix' and every path starting with '/wox/'):

secured_paths: ['/auth_path', /wix/, %r{\A/wox/}]

paths

Just like secured_paths, except these paths may or may not receive a Wix signed instance. If it does, the instance has to be valid. Calling request.env('wix.instance') in the controller may return nil (although the env key 'wix.instance' exists) if there was no instance passed.

secret_key

A String containing your Wix app's secret key.

Example:

secret_key: 'd245bbf8-57eb-49d6-aeff-beff6d82cd39'

(optional) strict_properties

A Boolean indicating if the instance properties of the Wix signed instance should be checked for completeness (true, default) or not (false). You should never need to set it to false and it's meant for debugging purposes only.