Net Biscuits - Custom Applications - Getting Started Guide V1.3

Version: 1.3 2010/03/31

Netbiscuits – Custom Applications Getting Started Guide

Copyright © 2010 Netbiscuits GmbH on Netbiscuits software and all related descriptions in this document. Netbiscuits is protected by copyright and all rights are reserved, including the rights to translation, copies, and reproduction using photomechanical or electronic systems. Protected trademarks, brand names etc. are not explicitly stated as such in the text. The lack of such identifiers in no way implies that the terms are not free names as defined by applicable trade mark and brand name legislation. Names of people and companies used as examples are always fictitious.

The information in this document has been carefully checked and can be considered reliable. Nevertheless, no guarantee can be given for the accuracy of the information in this document. In particular, no pledge can be given as to the suitability of the products described here for specific purposes. Netbiscuits retains the right to alter the products and product information specified here. Netbiscuits accepts no liability from events arising from the usage of the products described here. Issue of this document is not accompanied by licenses entitling you to use the listed products, nor products of Netbiscuits or of other companies.

Date Editor Comment Version

2009-07-29 CR Initial Draft 0.1

2009-08-04 CR Completed “Send Coupon Messages” 0.2

Table of contents page

1 Purpose of this document ........................................................................................................ 4

2 Reasons to use Custom Applications ........................................................................................ 4

3 Overview & System Architecture .............................................................................................. 4

4 How to set up a Custom Application ......................................................................................... 6

4.1 Login .......................................................................................................................................................... 6

4.2 Create a new Custom Application ............................................................................................................ 6

4.3 Configure your Custom Application .......................................................................................................... 6

4.4 Create a BiscuitML Application on our server .......................................................................................... 8

4.5 Configure your Firewall and Web- and Application-Server .................................................................... 10

4.6 Upload and manage Media files ............................................................................................................. 11

5 Create DNS entry for Friendly URLs ........................................................................................ 12

6 Preview your application ....................................................................................................... 14

7 Getting Help .......................................................................................................................... 14

8 Ressources on the Web .......................................................................................................... 15

4 / 15 © 2010 Netbiscuits GmbH

Netbiscuits – Custom Applications |Getting Started Guide

Purpose of this document

1 Purpose of this document Netbiscuits offers two types of applications: Standard and Custom Applications. This Getting Started Guide should give you an overview about when you should use a Custom Application and how you can set it up.

2 Reasons to use Custom Applications If one or more of these statements apply, it is recommended to use a Custom Application:

• You prefer to create pages with BiscuitML-Markup (XML) using your favourite IDE or

Editor rather than using the Netbiscuits Sitebuilder

• You want to develop a mobile portal with dynamic content sourced from a local backend

system (e.g. Database, Content Management System, Content-API, XML-Feed etc.)

• You need to connect your portal to other backend systems for processing user input

(registrations, polls, uploads, etc.)

• You want to integrate your application with a backend system for user authentication,

managing user accounts, deliver personalized content per user, etc.

• You need more control over the generated biscuit code. You need to run your own code

and decide what biscuits to put on a page dynamically, based on device parameters or

type of users

• You want to log user interactions yourself and analyze it on your side

In all other cases it is probably easier to use a Standard Application instead.

3 Overview & System Architecture In a Custom Application scenario, the Netbiscuits platform is working similar to a proxy server.



Overview & System Architecture

When a mobile device requests a URL of a Custom Application (mobile portal), this HTTP-request will be routed to and processed by the Netbiscuits platform. In a first step, Netbiscuits will forward the HTTP-request to your Web- & Application-Server (e.g. Apache, Tomcat, IIS, etc.) which hosts the BiscuitML Application. As in a normal web application, you will process the request and retrieve content from a Content Management System or database for example. Instead of creating HTML output, your application has to send a HTTP response back containing a valid BiscuitML document. The BiscuitML markup will then be processed by the Netbiscuits platform and be transcoded into the right markup (XHTML MP, WML etc.), specificially optimized for the mobile device that sent the initial request.

Although BiscuitML pages can be static pages, in most cases you would create dynamic applications, of course. You can do that by using your preferred programming language like Java, PHP, C#/VB.NET, etc., whatever you find useful to create dynamic web applications. Plugins for certain IDEs are available as well, which make development with BiscuitML easier.

The page content itself and also images that should be displayed inline in the pages of your mobile portal can reside on your Web- and Application server. Other multimedia files, especially those used as downloads (e.g. wallpapers, videos etc.), need to be uploaded to the Netbiscuits Media Repository first (please see chapter 4.6 for more information).



How to set up a Custom Application

4 How to set up a Custom Application Please follow the steps described below to set up a Custom Application.

4.1 Login Login to the myNetbiscuits section on www.netbiscuits.com. If you don’t have a valid account, please register first by clicking on the "Register" button on the Home page:

4.2 Create a new Custom Application Go to the myNetbiscuits or Applications section and click on the "Create" tab in the upper right to create a new Custom Application.

4.3 Configure your Custom Application In the next step, you can set the configration of the Custom Application.

http://www.netbiscuits.com/�




First, select an Application Name, which is used as an identifier for your application in different areas (the Application Name becomes part of the URL, Reports can de drilled down based on the Application Name, etc.). Then enter a brief description of your app.

For each application configured in Netbiscuits, a default URL is configured automatically, which can be used by mobile devices to access it. The default URL always has the structure:

http://apps.netbiscuits.com/[Customer-ID]/[Application-Name]

If visitors to your site have to type this URL in on their phone (instead of receiving it via SMS or similar), you might consider setting a Friendly URL. A "Friendly URL" is actually a subdomain on a domain you own. It should be short and easy to remember, for example “m.mydomain.com”. End-users can then use the Friendly URL to access the mobile portal. After setting a Friendly URL for the Custom Application, please remember to configure the subdomain on your DNS Nameserver (see chapter 5 for more information).




It is important that you enter the Backend URL to your Web- and Application-Server, which Netbiscuits uses to request BiscuitML documents from. This has to point to the root folder where your BiscuitML application is located. (i.e. http://myappserver.mydomain.com/myapp/). You need to configure a "default document" on your server i.e. "index.jsp", which must deliver BiscuitML (Also see chapter 4.4).

If your Web- and Application-Server requires authentication, please set a Login and Password accordingly after checking “Extended Parameters”.

Click on “Create Custom Application” when finished.

4.4 Create a BiscuitML Application on our server After you have configured the Custom Application on Netbiscuits, you can download IDE-Plugins, if you haven’t done so before. A good starting point for creating code on your server is to download some of the samples from the Developer Community / Downloads section.

The Forum holds tips and tricks as well as frequently asked questions in case you run into problems.




You can also use the following markup and store it in the default document of your BiscuitML application:




<?xml version="1.0" encoding="ISO-8859-1"?> <page title="Netbiscuits" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation= "http://www.netbiscuits.com/schema/netbiscuits.xsd"> <container> <column> <TEXT> <headline>[br]It works![br][br][br]</headline> </TEXT> <SEPARATOR> <hr/> </SEPARATOR> <TEXT> <styles> <style name="color" value="#414141"></style> <style name="bgcolor" value="#FFFFFF"></style> </styles> <richtext> [br]powered by net[color="red"][b]biscuits[/b][/color]™ </richtext> </TEXT> </column> </container> </page>

4.5 Configure your Firewall and Web- and Application-Server Please follow the steps described below to ensure your BiscuitML application (the "Backend URL") can be accessed from the Netbiscuits platform:

• Configure your firewall, so that your Web- and Application-Server is accessible from the

internet via HTTP protocol (TCP Port 80 by default).

• Configure your BiscuitML application on your Web- and Application server. You can use

Virtual Hosts and Websites.

• Set a default document for the BiscuitML application (e.g. “index.jsp”, “index.do”,

“default.aspx” etc., depending on your programming language. Store the BiscuitML

example markup (see above) in your default document.

• Set the content type for all BiscuitsML documents to “text/xml”. Note: for dynamic

pages, this can also be set with the programming language you use. All the calls to your

backend application should deliver BiscuitML (see the BiscuitML-Reference and the

BiscuitML Getting Started Guide in the Downloads section for instruction). Other than

that, the Application can be set up much like you would set up a normal HTML Web

application.

• Set authentication (Basic Authentication using Login/Passwort) on your Web- and

Application-Server if you like.

http://www.netbiscuits.com/biscuitmlreference�

http://www.netbiscuits.com/c/document_library/get_file?folderId=17218&name=DLFE-1202.pdf�




Please refer to de documentation of you Firewall or Web- and Application-Server for further information.

Now make sure that the BiscuitML application is available at the Backend URL you configured before and responding with the BiscuitML example markup. Use a PC outside your local network to check this.

Next, check if your Custom Application is working properly by requesting the default URL you can see when clicking on “Edit” in the Application Manager on Netbiscuits (like: http://apps.netbiscuits.com/[Customer-ID]/[Application-Name]). You can check either with your webbrowser or a real mobile device. The result should look like this if you used the BiscuitML markup example above):

Now you can start changing the markup of your first page, adding dynamic content to it (taken from a database, CMS etc.) via the coding environment of your choice (asp .NET, jsp, php, etc.) and adding further pages.

Further information/other documents:

• For more information about creating BiscuitML Applications see the “BiscuitML – Getting

Started Guide” and “BiscuitML Reference”

• Download “Netbiscuits .NET-Controls” or one of the BiscuitML Code Samples

All documents can be downloaded from: http://www.netbiscuits.com/downloads

4.6 Upload and manage Media files

In order to make use of downloadable Media Files like wallpapers, ringtones, videos etc. you have to upload the files to the Netbiscuits Media Repository first.

http://www.netbiscuits.com/downloads�



Create DNS entry for Friendly URLs

The Media Repository takes care of the proper transcoding of uploaded files (audio, video and wallpapers) into various formats required by mobile devices. In the Media Repository Administration Web-Frontend, you can fetch the ID of a Media Item or a Media Folder you can insert into your BiscuitML code to create links to downloadable media stored in the Media Repository.

Further information/other documents:

• Please refer to the “Media Repository - Getting Started Guide” for more information

about the management of media files

• The “BiscuitML – Getting Started Guide” contains detailed instructions on how to

integrate media files in BiscuitML applications

All documents can be downloaded from: http://www.netbiscuits.com/downloads

5 Create DNS entry for Friendly URLs If End-users have to type the URL of your Custom Application in on their phone (instead of receiving it via SMS or similar), you might consider setting a Friendly URL. A Friendly URL is actually a subdomain on a domain you own. It should be short and easy to remember, for example like “m.mydomain.com”. End-users can then use the Friendly URL to access the mobile portal.

If you want to use a Friendly URL, please create a CNAME entry in your DNS-Server, which points to Netbiscuits. For example, if you own the domain „mydomain.com“, and you want



Create DNS entry for Friendly URLs

to use „m.mydomain.com“ as a Friendly URL, please add a DNS entry like this on your Nameserver for the domain “mydomain.com”:

m CNAME apps.netbiscuits.com

After you have set the DNS entry, you can validate it by ping’ing the subdomain. It should show a response like this:

C:\>ping m.mydomain.com Pinging apps.netbiscuits.com [xxx.xxx.xxx.xxx] with 32 bytes of data: Reply from xxx.xxx.xxx.xxx: bytes=32 time=26ms TTL=119 Reply from xxx.xxx.xxx.xxx: bytes=32 time=26ms TTL=119 Reply from xxx.xxx.xxx.xxx: bytes=32 time=26ms TTL=119 Reply from xxx.xxx.xxx.xxx: bytes=32 time=26ms TTL=119 Ping statistics for xxx.xxx.xxx.xxx: Packets: Sent = 4, Received = 4, Lost = 0 (0% loss), Approximate round trip times in milli-seconds: Minimum = 26ms, Maximum = 26ms, Average = 26ms C:\>

Note: Please do not set a HOST DNS entry which points to the IP address of apps.netbiscuits.com, since this might change without notice.



Preview your application

6 Preview your application To preview your Custom Application, go to the My Applications section, find your application and expand it using the button. Then click on the “Simulator”-Link next to the Custom Application. On the following screen, you will see the content of your Custom application in a phone simulator.

You can click on links in the pages and scroll with the scrollbar on the right. Other phone skins can be selected from the drop-down box on the top.

Of course you can enter the URL of your Custom Application on a mobile device or in a web-browser as well.

7 Getting Help If you need further information and help, there are several places where it could be found: If you need more information on the biscuits, about recent developments that might not be integrated in the SiteBuilder yet, you can check the BiscuitML reference. It is mainly meant for Custom Application programmers but you might as well insert a biscuit with help of the SiteBuilder Markup biscuit.

In the Netbiscuits downloads section you find the latest Getting Started Guides as well as more advanced information on the Netbiscuits features. From the Netbiscuits homepage at http://www.netbiscuits.com, go to the Developer Community tab and there click the “Downloads” link.

To get some experience in using the SiteBuilder and to learn more about new features, it is always a good idea to have a look on the templates that come with the SiteBuilder. Create




Ressources on the Web

new Standard Applications using a template, have a look on the pages and see how they are built.

The Netbiscuits developer forum is another good starting point for collecting information. Several Netbiscuits developers are requesting support and provide advanced insight into the newest developments of Netbiscuits community. In case you did not find what you need, contact Netbiscuits support. Netbiscuits provides 24/7 support, so if in doubt contact our friendly support team by email:

[email protected]

8 Ressources on the Web Netbiscuits (http://www.netbiscuits.com/) Guides and Downloads (http://www.netbiscuits.com/downloads) Netbiscuits BiscuitML Reference

http://www.netbiscuits.com/c/document_library/get_file?folderId=17217&name=DLFE-2701.pdf

mailto:[email protected]�


http://www.netbiscuits.com/downloads�

http://www.netbiscuits.com/c/document_library/get_file?folderId=17217&name=DLFE-2701.pdf�

Documents

Net Biscuits - Custom Applications - Getting Started Guide V1.3