Using the Sandbox to test your Commerce Central app

Once you create an account on Commerce Central, you'll have an app dashboard with all of the essential information about your app. Click on the name of your app in the left-hand navigation pane to see it.

The top of this page shows a preview of the app card that will appear in the Commerce Central app gallery for your app, with the app metadata that you've provided. Below that are the API credentials that you will need to code against the Commerce Central API. These comprise the app token and the app secret. The app token is your app's "username" in the system, the way that your app identifies itself. The app secret is known only to you and to Yahoo. It is used for generating passwords and should otherwise be kept hidden.

At the bottom of the app dashboard is the "test account" section. Each app developer is automatically given a testing account to begin developing their app against. This part of the dashboard gives you all of the information you need to interact with the testing app: the store id and the connection password. It also has some code prewritten for you to make integration easier.

The store id is a short string that is used in API calls to identify which store you want to interact with. The connection password is a store- and app-specific password for authenticating your API calls.

Commerce Central API calls provide a simple REST interface for data about a store. They use HTTP basic auth, with your app token as the username and the connection password as the password. Each call builds on a base URL, which looks like this:

[app token]:[connection password]@sandbox-api.lexity.com/api/v1/store/[store id]

Then you append a further path to the URL to access store resources, like so:

[app token]:[connection password]@sandbox-api.lexity.com/api/v1/store/[store id].json
[app token]:[connection password]@sandbox-api.lexity.com/api/v1/store/[store id]/script_tags.json
[app token]:[connection password]@sandbox-api.lexity.com/api/v1/store/[store id]/products.json

All of available endpoints are detailed further in the documentation. Currently, only the json version of the API is available. The testing accounts section has a link to test the API in your browser and a sample CURL command to test the API from the command line.

Getting products data is as simple as hitting the products.json URL shown above. Each testing store is set up with the same set of fake data to test with.

To get your javascript code onto a store webpage with the Commerce Central API, you need to add it to the store by hitting the script_tag endpoint:

curl -X POST -H 'content-type: application/json' -d '{"script_tag": {"src": "[endpoint url]", "event": "onload"}}' '[app token]:[connection password]@sandbox-api.lexity.com/api/v1/store/[store id]/script_tags.json'

Then, when a customer visits a page on that store, the following script tag will be added to the page:

<script src="[endpoint url]"></script>

This allows you to add arbitrary javascript to the page, without requiring the store owner to edit their html. When your app is live this will happen automatically as the lexity script tag on the page pulls in your code.

However, this process is a little more complicated for testing apps. Your "store page" might be a full-fledged online store on yahoo stores, or it might just be a simple static html page running off of localhost. To connect your test environment to the Commerce Central servers you will have to add a little bit of javascript to the head of each page you want to test with. That code is at the bottom of the "Test your app" section, labeled "Instrumentation code". It should be copied into the html of each page of your test site, just above the closing </head> tag.