Unless you've been living under a rock the past months, you know all about the open-source module called MobileCenter, which enables iOS devices to access EPiServer sites.

I recently tried the installation on a demo site hosted at Epinova, and while the installation was quite simple, the official installation guide  has a few minor errors which may lead to some head-scratching.
Here's a quick walkthrough of the installation process, pointing out what I think is missing in the installation instructions at CodePlex.

Overview:

UPDATE: This is not a complete guide, you should still read the official installation instructions. The point of this blog post is to "fill in the gaps" where the official guide is unclear.

 

1. Set up an EPiServer CMS 6 site

MobileCenter requires EPiServer CMS6 (because of the gadgets functionality), so set up a new site or find an existing site to use. If setting up a new site, it's a good idea to install the Public Templates package so you can quickly test the MobileCenter installation afterwards.

 

2. Download and install MobileCenter

Get the iOS MobileCenter app at the App Store (free).

Get MobileCenter for your server here: http://mobilecenter.codeplex.com/releases/view/53233#DownloadId=154047

Note: The install guide (Step 1: Installing the package > Quick installation) states that you should unzip the downloaded file. This is not necessary.

Start Deployment Center and select EPiServer 6.0.530.0 > Install a module from a compressed file

Browse to the .epimodule file, then select the CMS 6 site that you want to install to. Done.

 

Now, some changes in web.config are necessary.

Note: If your server is running IIS6, some manual changes are required, as the install guide is written for IIS7:

"Enable basic authentification to securely connect to the dashboard and the web service from the iOS app. For IIS 7 add a module under /configuration/system.webServer/modules:"

<add name="BasicAuthentication" type="EPiServer.Security.BasicAuthentication, EPiServer" /> 

In IIS6, you won't find <system.webServer><modules>. Instead, under <system.web><httpmodules> you will find that the BasicAuthentication line mentioned above is already inserted, but commented out. All you have to do is un-comment the line.

 

To use the Google Analytics gadgets, you'll need to add the following lines to the <appSettings> section in your web.config (or appSettings.config if you have split the config):

<appSettings>
<add key="AnalyticsGadget.Username" value="username" />
<add key="AnalyticsGadget.Password" value="password" />
</appSettings>

Of course, remember to put in your own Google Analytics username and password above.

Note: After adding the appSettings settings, your site might need to be restarted to take effect. I experienced the "Captcha required" error described in Jeff Wallace's blog post until I did an IISReset, which fixed the gadgets.

Note2: The changes described in Jeff Wallace's blog post is already implemented in the release version of MobileCenter, so there's no need to update any code.

 

3. Setting up access rights

In Admin mode, create a new group, e.g. TouchUsers.
At the same time, create a new user (e.g. TouchUser) and add it to your new group.

Note: This is not covered in the install guide: Make sure to give your new group Read access to the startpage, and Read/Create/Publish access to the newspage, otherwise they won't be able to use gadgets like Create News. The MobileCenter iPhone/iPad app does not show an error when trying to publish without sufficient rights, it just does nothing :-)

Open web.config and add the TouchUsers group to the following sections:

<Configuration><location path="yourcmsuipath"><system.web><authorization><allow roles="WebAdmins, WebEditors, Administrators, TouchUsers">

<Configuration><location path="WebServices><system.web><authorization><allow roles="WebAdmins, WebEditors, Administrators, TouchUsers">

 

Next, give your user group access to act as a webservice.

Note: The installation guide seems to be missing a line here. It should be obvious, but anyway here's what you need to do:

  1. On the Config tab, select Security > Permissions for Functions.
  2. In Allow the user to act as a web service user, click Edit.
  3. Add your new user group and Save.

 

4. Adding gadgets

On your server, login to your site with your new user (TouchUser).

On the dashboard, add the iPhone Activator gadget. This will give you a list of available MobileCenter gadgets. Select a few, like Create News and Browser Statistics, then save.

Note: It is not necessary to check the box for the iPhone Activator in the list.

 

5. Testing

Open the MobileCenter app on your mobile device. Add your site details, save and connect.

You should now be logged into your site on your mobile device, and the gadgets you selected should be visible :-)

 

Tips and Troubleshooting

No landscape mode

The MobileCenter iPhone/iPad app currently does not support landscape mode.

Uploaded images always get cropped

Images uploaded from the camera or picture library using the Create News gadget, get cropped to a square size. Otherwise the image upload would timeout on a 3G connection.

New property "NewsRoot" required for Create News gadget

On your start page, create a new property called "NewsRoot" (of type Page). Point this to the page where news should be published.

Pagetype "[Public] News Item" required for Create News gadget

The Create News gadget is hardcoded to use a pagetype called "[Public] News Item" when publishing news. If you don't have such a pagetype, create it or modify the source code to your needs.

 

Error: Uploading images: "Error uploading images"

#1 When adding your site settings in MobileCenter, add a slash / to the end of the url, like "www.mysite.com/"

#2 The image uploader in MobileCenter tries to use a folder called /Global/iPhoneUploadedImages/ , which should have been created automatically on first upload.

If it has not, create this folder manually and give your touch user group Read/Write/Change access to it. Uploading should now work.

 

Error: Browser/Visitor Statistics gadget: "Captcha required" exception

Check that correct Google Analytics username/password is inserted in your <appSettings> section (web.config or appSettings.config).

Try to restart the site in IIS and see if this removes the error.

 

The source code for MobileCenter is available at CodePlex:

http://mobilecenter.codeplex.com/SourceControl/list/changesets