App Templates specification

App Templates is an Estimote Cloud feature which enables users to generate themselves apps powered by the Estimote stack from predefined templates. Try it out yourself, or read more about it in our blog post: A prototype is worth a thousand meetings.

This specification outlines what it takes to create your own App Template. If you:

  • have an idea for a great template,
  • already wrote an app showcasing an example beacon use case,
  • have a technology that integrates with Estimote’s stack,

… feel free to reach out and let’s chat about getting your template into Estimote Cloud.

What’s ahead (aka Table of Contents)

What makes a good template

  1. It should showcase an actual use case.

    Do: “how to show a notification when on the lock screen when users enters the store.”
    Don’t: “how to do beacon monitoring.”

    Do: “how to trigger an automatic payment when user leaves the store.”
    Don’t: “how to integrate Estimote SDK and Payment Solution X SDK in a single project.”

    Yes, the difference is subtle (you do need to use monitoring to show a notification on a lock screen!), but it’s all about focusing your template on answering the right question.

  2. It should be easy to modify and adapt to one’s own needs. Use good programming patterns and practices to make it easy to swap out entire subsystems of your app, change the text messages and imagery, etc.

  3. It should be easy to understand. Writing readable code is an art—even more so when the audience is not your colleagues, but programmers all over that world with different skill levels, familiarity with the beacon technology, etc.

How it works

An App Template is a regular app project (e.g., an Xcode or an Android Studio project) in which certain parts have been substituted for placeholders. When generating an app from an App Template, Estimote Cloud will replace these placeholders with actual values.

These placeholders are:

  • %APP_NAME% — CamelCase’ified name of the app, with a few random characters appended for uniqueness. For example, if the user names their app “Good ol’ Hello-World”, %APP_NAME% could turn out to be “GoodOlHelloWorldN1x”

  • %ORG_NAME% — organization name (e.g., “Estimote, Inc.”), as provided by the user in their Estimote Cloud profile

  • %ORG_ID% — CamelCase’ified version of %ORG_NAME%. For the above-mentioned example of “Estimote, Inc.”, it would be “EstimoteInc”

  • <#App ID#> and <#App Token#> — the app’s unique ID and access token, required for initializing the Estimote SDK

  • %BEACON_{n}_UUID%, %BEACON_{n}_MAJOR%, and %BEACON_{n}_MINOR%, where {n} are numbers from 1 to the number of beacons the template requires — UUIDs, majors, and minors of the beacons selected by the user to work with the app

The substitution takes place in all non-binary files. In addition to that, %APP_NAME% and %ORG_ID% placeholders are being replaced in names of directories.

iOS templates

We support Xcode projects in both Objective-C and Swift. The general structure of the template should look somewhat like this:

%APP_NAME%
├ %APP_NAME%
│ ├ AppDelegate.swift
│ ├ Info.plist
│ ├ ObjCBridge.h
│ ├ ...
│ └ Estimote
│   └ EstimoteSDK.framework
└ %APP_NAME%.xcodeproj
  └ ...

Pay attention to introduce appropriate placeholders in the following files:

  • *.swift, *.m, *.h, *.storyboard
  • %APP_NAME%.xcodeproj/project.pbxproj
  • %APP_NAME%.xcodeproj/project.xcworkspace/contents.xcworkspacedata

Estimote SDK

Your project must include an Estimote directory and group, and the EstimoteSDK.framework is required to be placed in that directory. This directory is also a good candidate for all of your Estimote SDK–related classes, wrappers, helpers, etc.

When generating a project, the EstimoteSDK.framework will be replaced with the newest, publicly available version of the Estimote iOS SDK.

Make sure to initialize the Estimote SDK with the App ID and App Token:

ESTConfig.setupAppID("<#App ID#>", andAppToken: "<#App Token#>")
[ESTConfig setupAppID:@"<#App ID#>" andAppToken:@"<#App Token#>"];

A good place to put this? The AppDelegate’s didFinishLaunching method.

Organization name

In the project.pbxproj file, which you’ll find inside the %APP_NAME%.xcodeproj directory, make sure the ORGANIZATIONNAME attribute is white-space–proof:

ORGANIZATIONNAME = "%ORG_NAME%";

This is wrong: (note the missing quotation marks)

ORGANIZATIONNAME = %ORG_NAME%;

File headers

Use simplified file headers:

//
//  ViewController.m
//  %APP_NAME%
//

… or omit the file headers completely. Don’t leave the default, Xcode-generated file headers:

//
//  ViewController.m
//  %APP_NAME%
//
//  Created by John Doe on 02/30/84.
//  Copyright (c) 1984 John Doe. All rights reserved.
//

Android templates

We support Android Studio projects only. The general structure of the template should look somewhat like this:

%APP_NAME%
├ .idea
├ app
│ ├ src
│ │ └ main
│ │   ├ java
│ │   │ └ com
│ │   │   └ %ORG_ID%
│ │   │     └ %APP_NAME%
│ │   │       ├ MainActivity.java
│ │   │       └ ...
│ │   ├ res
│ │   └ AndroidManifest.xml
│ ├ app.iml
│ ├ build.gradle (Estimote SDK dependency goes here)
│ └ ...
├ gradle
├ %APP_NAME%.iml
└ ...

Pay attention to introduce appropriate placeholders in the following files:

  • *.java, *.xml
  • .idea/.name
  • .idea/modules.xml ($PROJECT_DIR$/%APP_NAME%.iml)
  • %APP_NAME%.iml (external.linked.project.id="%APP_NAME%")
  • app/app.iml (external.system.module.group="%APP_NAME%")
  • app/build.gradle (applicationId "com.%ORG_ID%.%APP_NAME%")

Estimote SDK

You must define the Estimote Android SDK as a Gradle dependency in the app/build.gradle file, e.g.: (adjust the version number accordingly)

dependencies {
    ...
    compile 'com.estimote:sdk:0.1.2@aar'
}

Make sure to initialize the Estimote SDK with the App ID and App Token:

EstimoteSDK.initialize(getApplicationContext(), "<#App ID#>", "<#App Token#>");

A good place to put this? The onCreate method of your main activity—or better yet, of your custom Application subclass.