BooXtream plug-in for WordPress / WooCommerce

Transcription

1 BooXtream plug-in for WordPress / WooCommerce Manual DRAFT Beta

2 Beta requirements: WordPress 4.2 or higher is installed WooCommerce 2.4 or higher is installed BooXtream contract, with access to BooXtream Dashboard Contract name: Password: The ZIP-file with the BooXtream plug-in for WordPress / WooCommerce called icontact-woocommerce-booxtream beta 0.x.y.zip This manual assumes basic knowledge of WordPress, WooCommerce and the possibilities of BooXtream. A valid BooXtream contract with access to the BooXtream Dashboard is required. More information: Icontact BV A. Hofmanweg 5a 2031 BH Haarlem Netherlands Phone: Fax: Skype: icontact Facebook: Sales: info@booxtream.com Tech support: support@booxtream.com Icontact BV This document contains confidential and proprietary information. All rights reserved. No part of this publication may be reproduced or utilized in any form or by any means, electronic or mechanical, including photocopying and microfilm, without prior written consent of Icontact BV. 2

3 Table of Contents 1 Read this first 1.1 BooXtream Basics 1.2 Invisible watermarking, visible personalisation 1.3 Ex Libris 1.4 Chapter footer 1.5 Disclaimer page 2 Plug-in installation 3 Plug-in configuration 3.1 Configure your BooXtream contract 3.2 Configure default settings 3.3 Additional WooCommerce settings 4 Managing your ebooks 4.1 Introduction 4.2 Need to know 4.3 Nice to know 4.4 Preparing an ebook in the BooXtream Dashboard 4.5 Configuring WooCommerce products for BooXtream ebooks 5 Selling your ebooks 5.1 Introduction 5.2 The ordering and checkout process 5.3 How WooCommerce and BooXtream work together 5.4 How the ebook downloads are presented to the customer 5.5 Use the BooXtream Dashboard for an overview of all transactions 5.6 Detailed transaction information 3

4 Chapter 1 Read this first 1.1 BooXtream Basics BooXtream is a tool to store, watermark and personalise ebooks. It creates download links to watermarked and personalised epub and / or Mobi ebooks and fulfils the download when an end user clicks on a link. When you are a BooXtream user, you have access to the BooXtream Dashboard. The Dashboard offers insight in all ebook transactions, account usage and ebook master file management. BooXtream can be integrated with a web shop and other ecommerce solutions. This manual describes the features of the readymade BooXtream plug-in for WordPress/WooCommerce. If you want to develop you own plug-in or API interface, check the BooXtream API manual with technical documentation for software developers which is available in the support section of the BooXtream Dashboard. You only can use BooXtream if you have a contract and bought some BooXtream credits, the 'currency' which is used to for the pay-by-use system of BooXtream. More information about the status of your contract and credits can be found in your BooXtream Dashboard. 1.2 Invisible watermarking, visible personalisation BooXtream uses 3 data fields with information about the end users to watermark and personalise the ebooks: 1 'Name' (shows up in personalised ebooks, see below) 2 ' address' (shows up in personalised ebooks, see below) 3 'Reference id' (only used for reports and transaction logging, it doesn't show up in the ebooks) When using the WooCommerce plug-in, these data fields are derived from the customer and order info. Every ebook processed by BooXtream will contain invisible watermarks and (optionally) a combination of visible extra's. The following visible personalisation features contain 'Name' and ' address' of the end user: a. a personalised ex libris image on the bookplate (the page directly after the cover) b. a footer text at the end of every chapter c. a personalised page (disclaimer page) at the end of the ebook. See the next pages for some examples of these options. 4

5 1.3 Ex Libris The Ex Libris is an user-defined image which will be inserted in the ebook directly after the title page. The image to use must be uploaded in advance using the BooXtream Dashboard. When used in an ebook, the name and address of the end user will be superimposed in the Ex Libris image. The usage of an Ex Libris is optional and can be configured in the plug-in. A sample Ex Libris image looks like this: Please note: there are strict specifications for the custom Ex Libris image file. It should be a png image of 424 pixels wide by 600 pixels high. The name and address will be placed in the top half of the image. The center of the message will be at 212*225. The name and address text will be superimposed in the light coloured area: 5

6 With the default text font (script), an Ex Libris will look like this: Please note: The text 'This ebook is licensed to' and the BooXtream logo is part of the image. If you want to add text and logo's to an Ex Libris, be sure to include these in the image file. The username and address are inserted by BooXtream. You can select the font used in the personalised Ex Libris. Choices are: Sans Serif Script Using the Sans font, one line (one field) can contain between 28 (W s) and 105 (i s) characters. With a mixed set, we think it s safe to assume that there is room for at least 56 characters. Using the Script font, one line (one field) can contain between 16 (W s) and 69 (i s) characters. With a mixed set, we think it s safe to assume that there is room for at least 32 characters. 6

7 1.4 Chapter Footer BooXtream allows for an automatically generated chapter footer text that is inserted at the end of every chapter in the ebook. The chapter footer contains name and address of the end user, with or without a date. The usage is optional. Please note: the text used is a standard text, but language dependant. If you need a custom footer text, please contact support@booxtream.com Example of a chapter footer without date: 7

8 1.5 Disclaimer page BooXtream allows for an automatically generated personalised disclaimer page that is added to the end of the ebook. This page will have its own entry at the end of the table of contents (TOC). The disclaimer contains placeholders for name and address of the end user. The usage of the disclaimer page and TOC entry is optional. Example of a disclaimer page without date: Example of a TOC entry without date: Custom disclaimer page BooXtream supports custom disclaimer pages, but this option is not supported in the Dashboard or plug-in. To enable a custom disclaimer page (with bespoke text and or graphics), please contact support@booxtream.com 8

9 Chapter 2 Plug-in installation Usually the installation of the WordPress / WooCommerce BooXtream plug-in is a onetime process. Open WordPress and login as a CMS administrator Click Plug-ins > Add new Click Upload Plug-in Locate the file icontact-woocommerce-booxtream.zip on your computer and click Install Now. The plug-in is now being installed Now click on Activate Plug-in Now the plug-in is activated. You will see the installed plug-in in the list with all plug-ins: The next step is to configure the plug-in for your BooXtream contract 9

10 Chapter 3 Plug-in configuration When you configure the BooXtream plug-in, you determine which BooXtream contract and account you will use for WooCommerce. The WooCommerce plug-in only works with one single configuration, so it works with one contract only. However, the configuration can be changed as needed, for instance to change contract, accounts or default settings. 3.1 Configure your BooXtream contract Click on WooCommerce > Settings Click on Integration Please note: if there are other plug-ins installed, they might share the Integrations tab. In that case, the BooXtream settings page is available via a secondary menu: Enter your BooXtream contract credentials and click Save changes The message No valid contract name or password given indicates that the contract credentials are invalid. If you don't have valid credentials, please contact sales@booxtream.com 10

11 Select account If the contract credentials are valid, the field Account name and a drop down menu with all available accounts appears. All these accounts belong to the same contract. Please select an account. This will become the account for this WooCommerce installation. You can change the account at any time if necessary. 3.2 Configure default settings The next 7 fields contains the default settings for the BooXtream plug-in. Please note: some of these values can be overwritten on product level when creating a BooXtreamable product. Moment of transaction This determines the moment when your shop contacts BooXtream to place the order and when a credit is deducted from your BooXtream credit balance. Usually this would be right after payment has been successfully processed or on order completion. Select 'Processing' or 11

12 'Completed'. See Chapter 5 Selling your ebooks for more information about this setting. Reference ID-prefix Ex Libris * Ex Libris font * Language * Download limit * Every WooCommerce order has an unique order #. Usually this is a auto-incrementing number. This order number is visible and searchable in the BooXtream Dashboard when viewing transactions, where it is called 'Reference'. Use this field to add a text prefix to this number, like MYWOOSHOP, so it's more easy to identify and search for orders in the Dashboard. Drop down selection with all available Ex Libris image files in your account. Use the BooXtream Dashboard 'Stored Files' section to upload and manage your Ex Libris image files. Select one of the three font choices for the variable text in the Ex Libris image: 'Sans serif', 'Script' or 'Serif'. Please note that the Sans serif font is slightly smaller and enables longer names. Drop down selection for the language used for all visible ebook personalisation texts (like Chapter Footer text and Disclaimer Page text). Enter a value from 1 to 9999 (times). This value represents how many times a download link can be activated before it expires. Days until download expires * Enter a value between 1 and 999 (days). This value represents the lifetime of a download link in days before it expires. When you click Save changes, the installation and configuration process is finished. You're now ready to enter or update your products. (*) The settings marked with * are default settings but can be overridden on product level. 3.3 Additional WooCommerce settings Please do not enable guest checkout on the Checkout Options page: 12

13 By default, after a customer paid the ebook, the BooXtream ebook download links become available in the account of the customer so the use of an account is required. Don't forget to enable the Registration Options on the Accounts page: Chapter 4 Managing your ebooks 4.1 Introduction The BooXtream plug-in adds an extra 'BooXtreamable' checkbox at every product within WooCommerce. When selected, a WooCommerce product is extended with several new value fields. These fields are used to configure a WooCommerce product in order to handle them by the BooXtream watermarking and personalisation platform. 4.2 Need to know WooCommerces supports all kind of products (physical and digital) with a zillion possibilities to describe them. You might even use WooCommerce already to sell books and ebooks. It is good to know that when the BooXtream plug-in is installed, your existing product catalogue in WooCommerce is not modified in any way. Even if you already have digital products like ebooks in your catalogue, WooCommerce keeps on functioning as before. Please note: the ebooks you might have uploaded to WordPress/WooCommerce will not be handled by BooXtream automatically. You need to upload the master files to BooXtream. In order to have BooXtream handle your ebooks, you need to configure every existing or new product to work with the BooXtream plug-in. This involves the following steps for every ebook: In the BooXtream Dashboard: Upload your master ebook files (in epub format) using the Stored Files tab. Only epub files are supported. Sorry, no pdf or Mobi (*). 13

14 Upload your custom Ex Libris image (in png format) using the Stored Files tab. Uploading at least one ex libris image file is necessary only if you plan to use the 'ex libris' visible personalisation feature in WooCommerce. In WooCommerce: Activate the BooXtreamable product checkbox for every product you want to watermark and personalise using BooXtream. Enter all required and optional BooXtream fields for every BooXtreamable product (ebook). (*) Although BooXtream doesn't support ebook master files in Mobi format, you can sell Mobi files with WooCommerce and the BooXtream plug-in because BooXtream can convert watermarked epub ebooks to Mobi. See the product options in chapter 4.6 below. 4.3 Nice to know Managing a product catalogue with ebooks involves the handling of a lot of product data and images. If you want to do it right, every ebook needs a full set of metadata and supporting files in addition to the master file. An ebook not only has a title and sometime a sub title, but also one or more contributors and other descriptive texts. Of course there is a cover image (in jpg or png), a description of the content, and perhaps you want to show reviews or want to offer a free sample to download. All of this is managed by you, using WordPress, WooCommerce and possible other plugins. BooXtream is unaware of all this metadata and not involved here, BooXtream only stores and manages the master ebook file. There might be a situation where you don't want to use BooXtream to watermark your ebooks. For instance, if you want to offer your customers a free download of a sample ebook, you might not want to have these free ebooks to be handled by BooXtream, since this costs a credit for every download. In this case you can use the standard WooCommerce method for selling digital products. Select Downloadable, en do NOT select BooXtreamable, like this: Of course, you now need to upload your master epub to WordPress/WooCommerce, not to BooXtream. 4.4 Preparing an ebook in the BooXtream Dashboard 14

15 To add an ebook in your WooCommerce product catalogue, you need to upload the master file in the BooXtream Dashboard. Open and log in with your contract credentials. Click on the Stored Files tab You can upload and delete single and multiple files. The repository accepts any file type (epub, txt, jpg et cetera), however only epub can be used as an ebook master file. png image files are used for the custom Ex Libris. Once uploaded, all epub files in the repository can be selected in WooCommerce using their file name. So please use a useful, descriptive filename which is not too long. Best practice is to use isbn.epub, eg epub or title.epub, like children_who_changed_the_world.epub Please note that upper case, space characters and special characters in the file name are not allowed. To upload one or more files, use the Upload files button. To delete files, first select the files to delete using, then click Delete selected files. To search for files in the repository, use the Search box. (More info and comprehensive documentation about the BooXtream Dashboard is available in the Support section of the BooXtream Dashboard). 4.5 Configuring WooCommerce products for BooXtream ebooks 15

16 Once your master ebook files are available in the BooXtream Stored Files repository, you can create or modify a WooCommerce ebook product. Let's add a new product in WooCommerce and make this an ebook that will be handled by BooXtream. Products > Add product The standard WooCommerce 'Add New Product' screen contains a lot of fields to enter. We assume you know WooCommerce, so we focus only on the BooXtream specific features. Select the 'BooXtreamable' checkbox After you select the 'BooXtreamable' checkbox, several new fields appear. Please note: BooXtream works completely independent from the standard WooCommerce Virtual and Downloadable product options. You can mix virtual and downloadable products with BooXtreamable products in the same web shop. 16

17 Ebook: Language: Download limit: Days until download expires: Generate download link for epub: Generate download link for mobi: Ex Libris: Chapter footer: Disclaimer: Select the ebook from the BooXtream Stored Files repository. The drop down menu contains all available ebooks. Use 'Refresh files' if you recently updated your ebooks repository using the BooXtream Dashboard. Drop down selection for the language used for all visible ebook personalisation texts (like Chapter Footer text and Disclaimer Page text). Enter a value from 1 to 9999 (times). This value represents how many times a download link can be activated before it expires. Enter a value between 1 and 999 (days). This value represents the lifetime of a download link in days before it expires. Select this box if you sell ebooks in epub format Select this box if you sell ebooks in Mobi format Drop down selection with all available Ex Libris image files in your account. Use the BooXtream Dashboard 'Stored Files' section to upload and manage your Ex Libris image files. Select this box if you want to activate the Chapterfooter ebook personalisation feature when selling this ebook Select this box if you want to activate the Disclaimer ebook personalisation feature when selling this ebook 17

18 Include date in visible watermarks: Select this box if you want to show dates in the Chapter footer text and/or Disclaimer text when using ebook personalisation feature when selling this ebook Selecting an Ebook file is required. All other fields are optional. The field values for Language, Download Limit, Days until download expires and Ex Libris only need to be entered if they differ from the default values entered during the configuration of the BooXtream plug-in (see Chapter 3.2). The default values are shown in grey. 18

19 A sample product looks like this. Please note that the BooXtream plug-in only manages the fields in the red block. All other fields and data are standard WooCommerce or enhanced by other plug-ins: 19

20 Chapter 5 Selling your ebooks 5.1 Introduction Once you've updated your product catalogue with one or more BooXtreamable ebooks you're able to sell them using WooCommerce. The BooXtream plug-in acts as a generic extension for WooCommerce. It does not modify the configuration of the shopping cart, the ordering process, the customer accounts nor the way confirmations are sent. All these WooCommerce features needs to be configured by you. The most important thing to know is that the watermarking and personalisation process is started when the status of an order changes to processing. That's the moment when BooXtream starts creating download links. 5.2 The ordering and checkout process Suppose we have a simple WordPress/WooCommerce based shop with one BooXtreamable ebook. It might look like this: Customers can add this ebook to their shopping cart. The shopping cart is the default shopping cart from WooCommerce, so it can accept any other product as well. By clicking 'Add to cart' this ebook is placed in the shopping cart. 20

21 By clicking 'View Cart', WooCommerce shows the current shopping cart. Please note that everything you see on this page is generated and managed by WooCommerce. If you want to customise this page you need to modify WooCommerce. When the customer clicks on 'Proceed to Checkout', the standard WooCommerce checkout dialog appears. Again, please note that everything you see on this page is generated and managed by WooCommerce. If you want to customise this page you need to modify WooCommerce. 21

22 When customising this page, please note that customer name and address are required as input values for the ebook watermarking and personalisation process, so do not delete these form fields and do not make them optional either. When the customer clicks on 'Place Order', WooCommerce uses its standard procedures to activate a payment provider and to receive the payment. The BooXtream plug-in comes into action after WooCommerce registers a successful payment transaction. When you don't have a payment provider installed, you should enable the order manually by clicking 'Processing' in the Orders screen: 5.3 How WooCommerce and BooXtream work together What happens when processing is the following: 1. WooCommerce knows that the order is final and that the ebook can be delivered. 2. The plug-in copies customer data (first name, last name, address) and order number (created by WooCommerce) and instructs BooXtream to watermark the selected ebook using this dataset. 3. BooXtream creates and stores an unique watermarked and personalised ebook in epub and / or Mobi format. 4. BooXtream creates the download link(s) pointing to these newly created watermarked and personalised ebook(s). 5. BooXtream returns these download links to the plug-in. 6. The plug-in adds the download link(s) to the order and the links become visible in the account of the customer. Depending on how WooCommerce is configured, these download links are shown to the customer, and / or ed to the customer as well, but this is not standard, 'out of the box' WooCommerce behavior. The BooXtream plug-in itself doesn't send s, it just provides WooCommerce with the download links. 22

23 5.4 How the ebook downloads are presented to the customer In the most simple, out of the box configuration, WooCommerce creates an account for the customer where the order and the download link(s) can be retrieved: When the customer clicks on the Order # or on the button 'View', the order details will be shown. These order details include the download link(s). If you have configured a BooXtreamable product to deliver a watermarked epub, it looks like this: When the customer clicks epub, the watermarked and personalised ebook will be downloaded. 23

24 Similarly, if mobi format ebooks are created, they will show here as well. Every product in your catalogue can be configured for epub, mobi or both: Important: ebook processing can take time. The watermarking and personalisation process of a large ebook (10 MB or more) can take several seconds. If a Mobi file is requested, it might take a few seconds more. This means that the Order Details screen might need to be refreshed / reloaded before the download link is be available for the customer. 5.5 Use the BooXtream Dashboard for an overview of all transactions To follow the status of this transaction, open the BooXtream Dashboard and select the tab Transactions: In this transaction screen, the WooCommerce order number appears in the column Reference, the user credentials are shown in Customer and Customer Name, and the ebook title is shown in the column Original filename. 24

25 The icons on the left side represents the current download status: In this case, the download link has not been activated yet. There are 5 download clicks available, and the expiration date is (which is 90 days after the order date). 5.6 Detailed transaction information When you click on a transaction, a detailed information screen is available for diagnostic and support purposes. This screen provides all necessary information about a single BooXtream ebook watermarking transaction. 25