Dashboard Reference Guide version 2.0 1
More information: Icontact BV A. Hofmanweg 5a 2031 BH Haarlem Netherlands Phone: +31-23-7505125 Fax: +31-23-7505123 Skype: icontact Twitter: @booxtream Facebook: www.facebook.com/booxtream Sales: info@booxtream.com Tech support: support@booxtream.com 2010-2015 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
Table of Contents 1 Read this first 1.1 BooXtream Basics 1.2 Visible personalisation 1.3 The BooXtream Dashboard 2 Dashboard login 3 Transactions 3.1 Overview 3.2 Search 3.3 Status 3.4 Detailed transaction information 4 Credits 5 Manual mode 6 Batch mode 6.1 Overview 6.2 Download output file with download links 6.3 Creating a new batch Creating a normal batch Creating a mail batch 7 Stored files 7.1 Repository management 7.2 Actions 8 Support 3
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. BooXtream can be integrated with a web shop and other ecommerce solutions. Please check the BooXtream API manual with technical documentation for software developers. By using the BooXtream Dashboard, BooXtream can also be used 'manually', which is explained in this document. 1.2 Visible personalisation BooXtream uses 3 data fields with information about the end users to personalise the ebooks: 1 'Name' (shows up in personalised ebooks, also used for mailing options) 2 'Email address' (shows up in personalised ebooks, also used for mailing options) 3 'Reference id' (only used for reports and transaction logging, it doesn't show up in the ebooks) These data fields can be supplied manually (see chapter 5) or by uploading a spreadsheet with these fields in CSV format (see chapter 6). 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 'Email 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
ex libris BooXtream offers a standard ex libris image, but also allows for an user-defined ex libris image that can be uploaded. The ex libris image contains the name and email address of the end user. The usage of an ex libris is optional. The standard ex libris image looks like this: The custom ex libris image file will replace the default ex libris provided by BooXtream. It should be a png image of 424 pixels wide by 600 pixels high. The name and email address will be placed in the top half of the image. The center of the message will be at 212*225. In the next picture, the light coloured area is where the name and email address text will be placed: 5
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 email address are inserted by BooXtream. You can select the font used in the personalised ex libris. Choices are: sans serif script 6
chapter footer BooXtream allows for an automatically generated chapter footer that is inserted at the end of every chapter in the ebook. The chapter footer contains name and email 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
disclaimer BooXtream allows for an automatically generated 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 email 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 API. To enable a custom disclaimer page (with bespoke text and or graphics), please contact support@booxtream.com 8
1.3 The BooXtream Dashboard The BooXtream Dashboard is a tool to manage your ebook master files, check all transactions and perform manual tasks. This first chapter directs you to the BooXtream basics. The other chapters in this manual describe all Dashboard features in depth. The most common tasks are: a Uploading and maintaining your master ebook files: see Chapter 7 Stored files b Creating a download link to a watermarked and personalised ebook for a single end user: see Chapter 5 Manual mode or use the action 'manual mode' in the ebook repository (see Chapter 7 Stored files) c Create several download links to watermarked and personalised ebooks for different end users: see Chapter 6 Batch mode or use the action 'batch mode' in the ebook repository (see Chapter 7 Stored files) d Create several download links to watermarked and personalised ebooks for different end users and start a mail job: see Chapter 6 Batch mode see Chapter 6 Batch mode, 6.3 Creating a mail batch or use the action 'batch mode' in the ebook repository (see Chapter 7 Stored files) e Check the status of a download link: see Chapter 3 Transactions f Check the amount of credits left: see Chapter 2 Dashboard 9
2 Dashboard login Go to the BooXtream Dashboard https://www.booxtream.com/dashboard Log in using the Contract name and Password (supplied by mail): The Dashboard opens on the Home Page: Choose one of the tabs: Transactions, Credits, Manual Mode, Batch Mode, Stored Files, Support See the next chapters in this Dashboard Reference Guide for a description of all functions. 10
3 Transactions The Transactions page contains all BooXtream transactions from the current account in reversed chronological order (most recent transaction first). All transactions are shown regardless if the transactions were created through the API, or by using the Manual Mode or Batch Mode. The Transaction page opens with the overview page. There is also a detailed page for every transaction. 3.1 Overview 3.2 Search Use the Search transactions field to show only transactions containing the search string. The following fields are searched: Reference, Customer Email, Customer Name, Original File Name. The search is full text using substrings. With the Search function it is easy to locate a certain end user or transaction. For instance: type 'John' and all transactions containing john, johnny, johnson etc. will be shown. type '9789058319532' and all transactions containing 9789058319532 will be shown. 3.3 Status The icons in the column Status indicate the BooXtream mode and status of the download link. The first column indicates the error status of the transaction: The transaction was successful. One credit was used. The transaction was not successful because of an error. No credits were used. Errors are usually caused by incorrect use of the API or when watermarking an invalid epub file. Please see the API manual for more information about errors. The second column indicates the BooXtream mode used for this transaction: The transaction uses the Delivery Platform mode (download links). 11
The transaction used the Delivery Platform mode, and the download link has expired The transaction used the Direct Mode. The third column indicates the use of the Stored Files mode. If empty, the master file was uploaded using the API or the Manual Mode. The transaction used a master file from the repository (Stored Files mode) 3.4 Detailed transaction information Clicking on a transaction opens the detailed view of that specific transaction. The information on this page depends on the type of transaction and the status of the transaction. This page can be used to debug a single transaction. It shows all relevant transaction information, like language, the settings used (ex libris, chapter footer, disclaimer, date) and current status. In the sample shown here, the transaction used the Delivery Platform mode (download links) and the download links were still valid and not yet activated. 12
When the download links are activated by the end user, the status will change. For instance, when the maximum number of downloads is reached, it looks like this: 13
4 Credits The Credits page contains an overview of all invoices. To download an invoice (pdf), click on To check the current status and amount of credits used, go to the homepage. To order new credits, send an email to info@booxtream.com 14
5 Manual Mode Use the Manual Mode to watermark and personalise a single ebook for a single end user. The Manual Mode is the fastest way to generate a single watermarked ebook, for instance to check the results of the visible personalisation options. The Manual Mode creates one (epub or Mobi) or two (epub and Mobi) download links. It is up to you to use the download link(s), for instance by copy and pasting a link and sending it using your own email application. The Manual Mode does not send emails. Use the Batch Mode if you want BooXtream to send emails. Even if you want to have BooXtream send only one mail, it is considered a batch. The master ebook can be uploaded in this Manual Mode screen or can be retrieved from your stored files repository (see chapter Stored Files). Please note: master (or source) files need to be in the epub format. Mobi is not supported as a master file, only as an output format. When you choose Output: Mobi, the watermarked epub is converted to a watermarked Mobi file by BooXtream. In the Manual Mode, the following fields appear: Epub file Output Reference ID Language Customer E-mail address Customer name Expires in # days Download limit Optional fields Upload the ebook to watermark. If the Batch mode was started from the Stored Files mode, the name of the preloaded epub is shown here Select 1 or 2 output file types: epub and or Mobi A text string that is added to the transaction. It can be used to register a project name or some internal order number Select the language of the ebook The email address from the end-user. This is used in the visible personalisation The full name of the end user. This is used in the visible personalisation Select the number of days the download links must stay operational. Any value from 1 day to 999 days. After this period, a download link is expired. Select the number of times a download link can be clicked. Any number from 1 to 9999. After this number of clicks, the download link is expired. Select one or more of these visible personalisation features. More info about Ex libris, Chapter footer, Disclaimer, Show dates in chapter 1.2 Visible personalisation options. 15
After clicking Submit the download links are created. When a single output file format is requested, only one download link is returned: When both epub and Mobi output formats are requested, two download links are returned simultaneously: Copy and paste the link(s) into an email and send it to the end user. Every download link created (and its current status) will be visible in the tab Transactions. 16
6 Batch Mode The Batch Mode can be used to watermark a single ebook for several different end users. It creates a spreadsheet file with download links or (when enabled) sends personalised template based emails with download links to different end users. To provide the Batch Mode with all end user information (user names, email addresses) you need to upload a CSV file (comma delimited values) with this data. Any spreadsheet application can export data in CSV format. The Batch Mode either returns the CSV file with an extra column containing the download links or it can directly start an email job using the Mandrill email infrastructure service. The email functionality has to be enabled by BooXtream support staff. You need at least one custom email template to use the email functionality. More info: support@booxtream.com Since the Batch Mode uses as many credits as there are lines (records) in the CSV spreadsheet, you can easily use hundreds or even thousands of credits in a single click. Please accustom yourself to the Batch Mode using your test account before using your (paid) production account. The test account is not charged. If you need additional support for the Batch Mode, please mail to support@booxtream.com 17
6.1 Overview The Batch mode pages opens with an overview of all current and previous batch jobs. If there were no batches, the page opens empty with two tabs 'Batches' and 'New Batch': If there are previous batches, the Batches page shows the history of all individual batches with an option to download a detailed report (in an Excel-compatible CSV format): Every line represents a single batch with one or more transactions. Date and Time shows when the batch was started. The icons and text 'Subject / Sent from' indicate the batch type: normal or mail. Download output file: this CSV file contains the current, up to date status of this batch job (including mail status info). Download input file: the original file supplied for this batch job, with user names an email addresses. 6.2 Download output file with download links To download all download links created in a single batch, click the corresponding button 'Download output file'. This file CSV can be opened in Excel or with a compatible spreadsheet application. Depending on the mode (normal batch or mail batch), it not only contains all user names, email addresses and download links but also the actual status of every mail sent. 18
Normal batch (without email option) If you had started a batch without the email option, you can download the Excel file with all download links by clicking on the corresponding Download output file button: When opened in Excel, this CSV file contains exactly the same items as the input file, supplemented with a download link for every user. If the input file looked like this: Then the output file looks like this (if the batch was started to create only epub output files): If the batch contains both download links for epub and Mobi, another column is added with the Mobi download links. 19
Mail batch If you had started a batch with the email option, the overview screen has some additional info about the different subject lines used in the mails. You can download the Excel file with all download links and the status of the emails by clicking on the corresponding Download output file button: When opened in Excel, this CSV file contains an up to date status of the mail process: The status could be: Sent everything was ok Hard-bounced <reason>, eg bad_mailbox error Rejected error Please note: since the handling of email on the internet takes time, the contents of this file may change. If opened directly after processing, the status of every end user can be 'Sent', but this could change to an error when the email cannot be delivered and a bounce is detected. The CSV file also shows whether or not the ebook has been downloaded. A value 1 in the column 'Opened' indicates that an end user has opened or viewed the email: 20
6.3 Creating a new batch Click on New Batch to create a new batch of watermarked and personalised ebooks. Depending on your contract and account setting, you have the option to create a Downloadable CSV or to create a email job. The email functionality has to be enabled by BooXtream support staff. You need at least one custom email template to use the email functionality. More info: support@booxtream In this example both choices are shown: to create a csv file containing download links (Downloadable CSV) and to send the download links directly to the end users (Mailing). Use the Downloadable CSV mode if you process and send the download links manually or by using a third party mailing solution. Use the Mailing mode to have BooXtream create the download links and start an email job using the Mandrill email infrastructure service. In both modes you have to prepare a csv-file containing the name and email address of the end users and reference identifiers. The file must start with a header and the individual fields must be separated by semicolons. Please ensure the file is encoded in utf8. An example of a valid csv file looks like this: customername;customeremailaddress;referenceid John Smith;johnsmith@example.com;refid1 Bill Johnson;b.johnson@example.org;refid2 The name and email address are used to personalise the ebooks. Depending on your choice, these values will be shown in the ex libris (page 2), the chapter footer and or the disclaimer page (last page). For examples, see chapter 1.2 Visible personalisation options. If you choose to send the batch directly to the end users, the email address in the CSV file is not only used for the personalisation, but also used as the send to address for the email job. 21
Creating a normal batch For a normal batch, the following fields appear: Epub file Output Batchfile Language Expires in # days Download limit Optional fields Upload the ebook to watermark. If the Batch mode was started from the Stored Files mode, a preloaded epub can be chosen Select 1 or 2 output file types: epub and or Mobi Upload the spreadsheet with the names and email addresses from the end users. This data is used for the visible personalisation of all watermarked ebooks. Select the language of the ebook Select the number of days the download links must stay operational. Any value from 1 day to 999 days. After this period, a download link is expired. Select the number of times a download link can be clicked. Any number from 1 to 9999. After this number of clicks, the download link is expired. Select one or more of these visible personalisation features. More info about Ex libris, Chapter footer, Disclaimer, Show dates in chapter 1.2 Visible personalisation options. 22
Creating a mail batch The main difference between a normal batch job and a mail batch job is the fact that the mail batch also sends personalised email messages to all end users. The email functionality has to be enabled by BooXtream support staff. You need at least one custom email template to use the email functionality. More info: support@booxtream It works similar to the normal batch, with added field for the email functions: From address email address of the publisher (or sender) From name corresponding name of publisher (or department) Subject subject line of every email Template the email design to be used. At least one template must be available. 23
After clicking Submit, the batch is processed and the mails are sent. Processing can take some time, depending on the number of end users in the CSV file and the size of the master ebook (in MB). When finished, the resulting screen shows the number of download links created and emails sent: For your own reference, a CSV file with all download links is created. All end users now receive an email in their inbox: The actual design of the email body is determined by the selected Template. Templates can be created and edited by the BooXtream support team. 24
7 Stored Files Use Stored Files to manage your epub repository with the master ebook files. 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 ebook master file. Mobi is not supported as a master file, only as an output format. All epub files in the repository can be referred to in the API using the Stored Files commands. Alternatively, all epub files can be used for manual watermarking (using the Manual Mode in the Dashboard) and for Batch Mode watermarking (using Batch Mode in the Dashboard). See 'Actions' below. 7.1 Repository management: 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. 7.2 Actions Use the buttons on the right side of every file for the following actions: Use this ebook as master ebook for the Batch Mode. The Batch Mode tab opens. Use this ebook as master ebook in the Manual Mode. The Manual Mode tab opens. Search for all transactions with this ebook. The Transactions tab opens. Download this file to your device 25
8 Support This page offers relevant information about BooXtream, manuals, useful tools to check the validity of epub files and enables you to contact our support team. Alternatively, you can send an email to support@booxtream.com 26