WordPress Plugin

Verge3D comes with a plugin for WordPress, the most popular content management system (CMS) in use (60+ million installations).

Verge3D for WordPress plugin offers the following features:

These features can work independently on each other. For example, you might want just the embedding, or you can handle orders received from a Verge3D application hosted somewhere else (such as on Verge3D Network etc).

Contents

Plugin sandbox

To try out the features of the plugin please check out the Verge3D for WordPress sandbox. It provides a safe environment that you can use to test your Verge3D apps.

Installation

Before installing the plugin, make sure you have at least WordPress 5.0. To upload applications on your server you need to have a modern browser such as Google Chrome, Firefox, Edge or Safari.

To install, simply:

In some cases, you might need to install the plugin from the Verge3D distribution (for example, when you're going to try a new feature available in the pre-release version of Verge3D). To do so, follow these steps:

After activation, try to upload some of your apps or create a test order to verify that plugin works as expected.

Please note, that your WordPress server configuration might have tight upload limits. If you experience troubles during uploading of your apps, you need to tweak the following settings in your php.ini file: upload_max_filesize = 128M post_max_size = 128M Check out the official PHP documentation for more info about php.ini configuration.

Uploading applications

Use the Applications admin menu to access Verge3D Applications screen:

Verge3D for WordPress applications

To upload new app, click Add New button, enter app name, then click Next. You'll see Manage Verge3D Application dialog. Click Choose Files, select an application folder, then click Upload:

Uploading Verge3D app to WordPress

On this form you can also configure iframe (canvas) size of your application and allow/deny fullscreen mode.

To embed Verge3D applications in your WordPress pages/posts use the following shortcode:

[verge3d id="YOUR_APP_ID"]

where YOUR_APP_ID is an ID of your application displayed in the table on the Verge3D Application screen.

Integrating with WooCommerce

WooCommerce is a popular e-commerce system which powers over 28% of all online stores. Verge3D offers a seamless integration with WooCommerce via this WordPress plugin and e-commerce puzzles.

Please refer to this tutorial article for the info on how to use this feature. You may also check out the following video.

For usage example, check out the following demo from the asset store: Drink Shop.

Uploading files

This feature allows the users to persistently store content created in Verge3D applications, such as taken screenshots, uploaded textures, and saved configurations.

To upload your file on the server use the following REST API method:

https://HOSTNAME/wp-json/verge3d/v1/upload_file/

Where HOSTNAME is the host name of your WordPress server, such as sandbox.soft8soft.com

Upon success this method returns the following JSON file with the info on the uploaded file:

{ "id": THE_ID_OF_THE_UPLOADED_FILE, "link": LINK_TO_THE_UPLOADED_FILE, "size": FILE_SIZE }

Use the link provided in the request to retrieve your file or use the ID and get_file REST API method:

https://HOSTNAME/wp-json/verge3d/v1/get_file/ID

Using puzzles

Use the send data and loaded data puzzles to upload your files. Parse the JSON fields of the API response by using the in dict ... get key ... puzzle.

The example below uploads the user-selected file specified in the "opened file" puzzle to the Soft8Soft sandbox and then saves the web address to that file in the link variable:

To retrieve/download your files use the load data and loaded data puzzles.

For usage example, check out the following demo from the asset store: Custom Image.

Receiving orders with order form

To handle regular orders sent by your Verge3D applications (by the place order or place order+ puzzles), add an order form to some of your WordPress page/post using the following shortcode:

[verge3d_order]

Then specify the link to that page/post as the "send to" parameter of the place order/place order + puzzles. Each time this puzzle is executed, your app will redirect users to your order form:

For usage example, check out the following demo from the asset store: Ring.

Receving orders in background via REST API

In some cases you might want to create custom experience for placing orders instead of redirecting users to the order page.

Say you want to create a basic table customizer. This is how your data might look like:

{ "user_name": "John Smith", "user_email": "john.smith@example.com", "user_phone": "+123456789" "items": [ { "sku": "table_top_white", "quantity": 1 }, { "sku": "table_leg_brown", "quantity": 4 }, ] }

You can compose this structure using the dictionary puzzles and then send it to the server using the "send data" puzzle.

To do this, assign a proper URL for your "send data" puzzle. This one looks like:

https://HOSTNAME/wp-json/verge3d/v2/place_order/

Where HOSTNAME is the host name of your WordPress server, such as sandbox.soft8soft.com

Managing orders

Use the Orders admin menu to access E-Commerce Orders screen:

The orders in this list are created automatically upon receiveing requests from Verge3D applications. You can use this screen for reviewing and managing customer orders.

Managing products

Use the Products admin menu to access E-Commerce Products screen:

Each product has the following fields:

Title
Human-readable product title such as "Verge3D for Blender" or "Spinner". This field is mandatory.
SKU
Product stock keeping unit. This value is used not only to manage orders by merchant, but primarily to reference product items in the place order + or send data puzzles. Basically, this value is used as product ID.
Price
Product price. Can be set to zero.
Download link
Optional link to a downloadable product.

Getting info about products

This feature allows the users receive information about products stored on server.

To use it, execute the following REST API method:

https://HOSTNAME/wp-json/verge3d/v1/get_product_info/SKU

Where HOSTNAME is the host name of your WordPress server, such as sandbox.soft8soft.com, and SKU is the product SKU.

Upon success, this method returns the following JSON file with the product info:

{ "status": "ok", "title": "Product Title", "sku": "SKU", "price": "Product price" "currency": "Currency symbol, such as $" }

Using puzzles

Use the load data and loaded data puzzles to get info about your products:

Plugin settings

Use Settings admin menu to modify the plugin global settings:

General tab

Currency
Currency used to store/display prices.
Price decimals
Number of decimal digits used to display prices.
Merchant info
Merchant info: company/brand, address, contacts, logo etc.
Order form fields
The fields your orders should include.
Order success text
Text to display when order successfully placed.
Order failed text
Text to display when order failed.

Mail tab

Order notification e-mail
Option is used to specify an e-mail address of the person responsible for managing orders. When a customer places a new order, you will be notified about this order on this e-mail.
Order e-mails "From"
Option is used to specify a name/e-mail of a person/organisation that is responsible for communicating with the customer. This can be a sales manager e-mail, some common address such as sales@yourcompany.com or just a no-reply address such as noreply@yourcompany.com.
New order notifications
Use these options to configure to whom new order notification emails will be sent to as well as subject, content and attachments of such emails.
Updated order notifications
Use these options to configure to whom order update notification emails will be sent to as well as subject, content and attachments of such emails.
Sales quotes
Use these options to configure subject and content of quote emails sent to your customers.
Invoices
Use these options to configure subject and content of invoice emails sent to your customers.

Documents tab

To use this feature properly you need to install Chrome/Chromium browser on your server. It will be operated in the so-called headless mode to convert HTML orders to PDF format. Specify the path to the Chrome/Chromium executable if you installed it in some custom directory or leave the path field blank if you installed it system-wide.

Please note, that it order to install Chrome system-wide you need to have admin access to the server. If you don't, download latest Chromium build, unpack it in some user-accessible directory on your server and then specify the path to the Chromium executable in the path field (e.g /home/ubuntu/chrome-linux/chrome).

PDF Generator
Path to the Chrome/Chromium browser to perform PDF conversion. Leave blank if you installed it system-wide.
Quotes
Additional content displayed in quote documents and time the quote is considered valid.
Invoices
Additional content displayed in invoice documents.

Payment tab

Paid status
Order status to set for successfull payments. For example, if you're selling physical goods, you might want to set the order status to Processing, that means that you're processing the order for shipment. If you're selling digital goods, you might want to set the status to Completed. In this case, the download link will be send to the customer by email.
PayPal
PayPal payment method activation checker and app's client ID. Use the following page for instructions on how to optain it.

Security tab

To make your server more secure, always disable features you don't use.

Enable REST APIs
Options are used to enable/disable the order management, persistent file storage, or product APIs provided by the plugin.
Cross-domain requests
Options is used to enable/disable cross-domain (originated from different hosts) requests to the REST APIs provided by the plugin.
Custom products
Allow receiving orders with custom product prices and/or SKUs.

Customizing e-commerce forms

To modify e-commerce forms copy the form templates located in the templates directory of the Verge3D plugin to your WordPress theme directory under the verge3d subdirectory.

For example, if you need to modify order email template:

WORDPRESS/wp-content/plugins/verge3d/templates/order_email_body.php -> THEME/verge3d

Where WORDPRESS is the root directory of your WordPress installation and THEME is the directory of your current theme.

Here is the list of templates you can customize:

Template File Description
order_email_body.php Order email body template. This template used both for order notifications sent to you and to your customers.
order_pdf.php Order email PDF attachment template. This template is used to generate HTML files which will be converted to PDF and attached to order emails.
order_form.php Order form template. This form is displayed to you customers on the pages where [verge3d_order] shortcode is present.
order_success.php Message displayed when the order was accepted.
order_failed.php Message displayed when the order was rejected.

Security Measures

When using custom forms for your e-commerce applications be sure to properly escape output data sent by your customers. Use the following guide for more info.

E-commerce protocol specification

The place order and place order + puzzles use the following protocol to handle orders. Orders are sent from the browser to server using HTTP POST requests with the following parameters:

POST parameters Description
v3d_items Order items. A JSON-encoded array with order items.
v3d_attachments[] Order attachments. This optional value must be an array of data URIs representing order attachments.

The order item has one of the following formats, depending on the puzzle you use. For place order:

Fields Description
title Order item title.
price Order item price.
quantity Order item quantity: number of units, weight, length, etc.

For place order +:

Fields Description
sku Order item SKU (stock keeping unit). This SKU is used as an ID to retrieve information about the product from the server.
quantity Order item quantity: number of units, weight, length, etc.

The more advanced JSON-based protocol uses the following set of parameters:

JSON fields Description
user_name Customer's full name (also used as billing name).
user_email Customer's e-mail address.
user_phone Customer's phone number.
user_comment Optional order comments.
items Order items. An array with order items.
attachments Order attachments. This optional value must be an array of data URIs representing order attachments.
user_address1 Billing address — line 1. In order to use this field, activate the Billing address option on the General tab.
user_address2 Billing address — line 2. In order to use this field, activate the Billing address option on the General tab.
user_city Billing address — city. In order to use this field, activate the Billing address option on the General tab.
user_state Billing address — state, county, or province. In order to use this field, activate the Billing address option on the General tab.
user_country Billing address — country. In order to use this field, activate the Billing address option on the General tab.
user_postcode Billing address — postcode/ZIP. In order to use this field, activate the Billing address option on the General tab.
shipping_address1 Shipping address — line 1. In order to use this field, activate the Shipping address option on the General tab.
shipping_address2 Shipping address — line 2. In order to use this field, activate the Shipping address option on the General tab.
shipping_city Shipping address — city. In order to use this field, activate the Shipping address option on the General tab.
shipping_state Shipping address — state, county, or province. In order to use this field, activate the Shipping address option on the General tab.
shipping_country Shipping address — country. In order to use this field, activate the Shipping address option on the General tab.
shipping_postcode Shipping address — postcode/ZIP. In order to use this field, activate the Shipping address option on the General tab.

Got Questions?

Feel free to ask on the forums!