Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

# Parse Encoded App Instance Data

When a user accesses your app through a client-side action, Wix provides data about the [app instance](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/about-app-instances) as an encoded query parameter to your app endpoints. This query parameter, encoded in base64, includes the `instanceId` along with site and user information. The data is also signed to ensure its integrity and authenticity. 

The encoded parameter includes a signature and the data:

```json
// Signature                                Data
vrinSv2HB9tqbnJ6RSwoMgVamAIxpmmsA0I6eAan960.eyJpbnN0YW5jZUlkIjoiYWZmNTAxNmQtMjkxNC00ZDYzLWEzOGMtYTZk...
```

The following sections show examples on how to parse the parameter in various programming languages.

## Node.JS

```javascript
const CryptoJS = require("crypto-js");
function verifyInstance(instance, secret) {
   // spilt the instance into signature and data
   var pair = instance.split('.');
   var signature = decode(pair[0], 'binary');
   var data = pair[1];
   // sign the data using hmac-sha1-256
   var hmac = CryptoJS.algo.HMAC.create(CryptoJS.algo.SHA256, secret);
   hmac.update(data);
   var hash = decode(hmac.finalize().toString(CryptoJS.enc.Base64), 'binary')
   return (signature === hash)
}
function decode(data, encoding) {
  encoding = encoding === undefined ? 'utf8' : encoding
  var buf = Buffer.from(data.replace(/-/g, '+').replace(/_/g, '/'), 'base64')
  return encoding ? buf.toString(encoding) : buf;
}
```

## PHP

```bash
public static function &isWixRequest() {
 
    list( $code, $data ) = explode( '.', $_GET[ 'instance' ] );
 
    if ( base64_decode( strtr( $code, "-_", "+/" ) ) != hash_hmac( "sha256", $data, '[APP_SECRET]', TRUE ) ) {
        die();  // Report error
    }
 
    if ( ( $json = json_decode( base64_decode( $data ) ) ) === null ) {
        die();  // Report error
    }
    return $json;
}
```

## Java

```java
----------------------------------------------------------------------
The following example uses the apache commons-codec library for Base64 encoding and Jackson for JSON parsing.
 
The Maven dependencies of those libraries are:
 
    commons-codec
    commons-codec
    1.6
 
    com.fasterxml.jackson.core
    jackson-databind
    2.0.4        
 
-----------------------------------------------------------------------
 
import java.util.Arrays;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
 
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
 
import org.apache.commons.codec.binary.Base64;
 
public class WixSignatureDecoder {
 
 public final static JsonNode decodeSignature(final String signedInstance, final String secretKey) throws Exception {
  // initialization
  final SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HMACSHA256");
  final Mac mac = Mac.getInstance("HMACSHA256");
  mac.init(secretKeySpec);
 
  // split the signed-instance
  Base64 base64 = new Base64(256, null, true);
  int idx = signedInstance.indexOf(".");
  String signature = signedInstance.substring(0, idx);
  String encodedJson = signedInstance.substring(idx+1);
 
  byte[] sig = base64.decode(signature.getBytes());
  byte[] mySig = mac.doFinal(encodedJson.getBytes());
  if (!Arrays.equals(mySig, sig))  {
      throw new Exception("signatures do not match");
  } 
 
     // objectMapper is jackson interface for reading JSON - one JSON serialization library in java
     return objectMapper.readTree(new String(base64.decode(encodedJson)));
 }
}
```

## Ruby

```ruby
def parse_instance_data(signed_instance)
    APP_SECRET = 'YOUR_APP_SECRET_GOES_HERE'
    signature, encoded_json = signed_instance.split('.', 2)
 
    # Need to add Base64 padding to make base64 decode work in Ruby. (ref: http://stackoverflow.com/questions/4987772/decoding-facebooks-signed-request-in-ruby-sinatra)
 
    encoded_json_hack = encoded_json + ('=' * (4 - encoded_json.length.modulo(4)))
 
    json_str = Base64.decode64(encoded_json_hack)
 
    hmac = OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, APP_SECRET, encoded_json)
 
    # bug in ruby. why are there '=' chars on urlsafe_encode ?!
 
    my_signature = Base64.urlsafe_encode64(hmac).gsub('=','')
 
    raise "the signatures do not match" if (signature != my_signature)
 
    JSON.parse(json_str)
 
end
```

> **Note:** According to the Base64 specification, the padding character (`=`) at the end of a URL-Safe Base64 encoded string is optional. Wix encoding doesn't include this padding character. In Ruby and Python, add the padding to the Base64 encoded values that you receive from Wix.

## See also

* [About App Instances](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/about-app-instances)