diff --git a/README.md b/README.md index 6d19bb9..02199f3 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,85 @@ # Estimote Mirror Android SDK -**Take control of the big screen from your Android app with [Estimote Mirror][]** - [Estimote Mirror]: http://blog.estimote.com/post/150398268230/launching-estimote-mirror-the-worlds-first -[![Feature requests](https://img.shields.io/badge/feature%20request-canny.io-blue.svg)](https://estimote.canny.io/mirror-display) -[![Apache License 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://tldrlegal.com/license/apache-license-2.0-(apache-2.0)) -[![Chat on Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/EstimoteMirror/Mirror-SDK-Android) +[![Download](https://api.bintray.com/packages/estimote/android/mirror-display-sdk/images/download.svg)](https://bintray.com/estimote/android/mirror-display-sdk/_latestVersion) +![Feature requests](https://www.bitrise.io/app/55cd8edc4f83f32e/status.svg?token=KN5gaUHiK2opILjxV8tcBg&branch=master) +![Apache License 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg) + +*This SDK allows you to take control of the big screen from your Android app with [Estimote Mirror][]*. + +**Main features:** + +* *Building Mirror experience based on mobile SDKs* - you can start prototyping your first Mirror application, using only mobile Display SDK. There is no need to upload any code or resources upfront to the Mirror. + +* *Pre-defined views* - No need to design your first Mirror app view. Android Mirror SDK lets you define customized screens based on pre-defined views; All you need to do is to declare basic styling and data content. + +* *Display rules based on proximity* - You can easily take control over Mirror-plugged screen with display rules. Building on top of screen proximity conditions i.e. when you're nearby the screen, you can define different screen behavior. -**Got a question?** Join us on [Gitter][], or head over to our [community forums][]. +* *Feedback from Mirror screen to mobile* - Whenever any display action has been triggered, your mobile app is being notified about it. You can handle successful screen change and perform further actions with your mobile app. -[Gitter]: https://gitter.im/EstimoteMirror -[community forums]: https://forums.estimote.com +Please check the rest of README to get further details. -**Table of Contents:** +We really appreciate your [feedback about our SDKs](#your-feedback-and-questions), thank you! -* [Getting started](#getting-started) - + [Hello, world!](#3-hello-world) -* [Documentation](#documentation) -* ["Work in progress" disclaimer](#work-in-progress-disclaimer) +# Table of Contents -## Getting started +* [Installation](#installation) +* [Quick start](#quick-start) +* [Your feedback and questions](#your-feedback-and-questions) +* [Changelog](#changelog) +* [License](#license) -### 1. Installation +# Installation + +## Prerequisities +* 1 [Estimote Mirror][] w/ **1.0.15+** firmware version. +* An account in [Estimote Cloud](https://cloud.estimote.com/). +* An Android device with Bluetooth Low Energy support. We suggest using Android 5.0+ (Lollipop or newer). + +## Maven/Gradle dependency Add Estimote's Maven repo to your **project's** build.gradle: ~~~ java - -allprojects { - repositories { - maven { - url "http://estimote.bintray.com/android" - } - // other repositories go here +repositories { + maven { + url "http://estimote.bintray.com/android" } } - ~~~ -Then add the Display SDK dependency to your **module's** build.gradle: +Then, add the Display SDK dependency to your **module's** build.gradle: ~~~ java -dependencies { - // ... - compile 'com.estimote:display-sdk:0.1.6' -} +compile 'com.estimote:display-sdk:0.1.7' ~~~ -### 2. Initializing Estimote SDK +## Obtain app credentials from Estimote Cloud + +To obtain Estimote Cloud credentials for your mobile application: + +1. Log in to your [Estimote Cloud](https://cloud.estimote.com/) account. +2. Go to *Apps* section and click **Add new app** option. +3. Select **Your own app** option. +4. Save your App Id/App Token credentials. + +## Initialize Estimote SDK in your Android project Initialize Estimote SDK in your Application class `onCreate()` method: ~~~ java // To get your AppId and AppToken you need to create a new application in Estimote Cloud. -EstimoteSDK.initialize(applicationContext, appId, appToken) +EstimoteSDK.initialize(applicationContext, , ); // Optional, debug logging. -EstimoteSDK.enableDebugLogging(true) +EstimoteSDK.enableDebugLogging(true); ~~~ -Ask for runtime `ACCESS_COARSE_LOCATION` permission (it is required to enable Bluetooth scanning since Android 6.0). You can use provided helper that will also check if Bluetooth adapter is enabled: +## Grant Android runtime permissions + +Ask for runtime `ACCESS_COARSE_LOCATION` permission - [ it is required to enable Bluetooth scanning since Android 6.0](https://developer.android.com/training/permissions/requesting). You can use provided helper that will also check if Bluetooth adapter is enabled + ~~~ java @Override void onStart() { @@ -69,61 +88,51 @@ void onStart() { } ~~~ -### 3. Hello, world! +# Quick start + +The following is simple example for showing Poster View on the screen. ```java -public class MainActivity extends AppCompatActivity { - - private MirrorClient mirrorClient; - - @Override - protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - - PosterViewData posterData = new PosterViewData.Builder() - .setHeader("Hello, world!") - .setBody("Programmable screen is here.") - .setImage("assets/shoe_big.jpg") - .create(); - - PosterViewStyle posterStyle = new PosterViewStyle.Builder() - .setTextAlign("center") - .setTextPosition(new Position(Horizontal.center(), Vertical.bottom(80))) - .setImagePosition(new Position(Horizontal.center(), Vertical.top(80))) - .create(); - - PosterView poster = new PosterView(posterData, posterStyle); - - this.mirrorClient = new MirrorClient.Builder(getApplicationContext()) - // replace with your own Mirror's ID - .useMirrorWithIds("9f1a787ad3764057311e043f63921917") - .setDebugModeEnabled(true) - .setRepeatableDisplayRequests(true) - .build(); - - this.mirrorClient.when(MirrorZone.NEAR).thenShow(poster, new DisplayCallback() { - @Override - public void onViewOperationDone(ViewOperation viewOperation, - com.estimote.display.view.View view) { - Log.d("Mirror", "Yay!") +//Java +MirrorClient mirrorClient= + new MirrorClient.Builder(this).build(); + +PosterViewStyle defaultPosterViewStyle= + new PosterViewStyle.Builder().create(); + +PosterViewData defaultPosterViewData= + new PosterViewData.Builder() + .setHeader("Congratulations!") + .setBody("You've just created a Poster View! \n Let's tweak it a little bit!") + .setImage("poster.jpg") + .create(); + +PosterView posterView = new PosterView(defaultPosterViewData,defaultPosterViewStyle); + +mirrorClient.when(MirrorZone.ANY).thenShow(posterView,new DisplayCallback(){ + @Override + public void onViewOperationDone(ViewOperation viewOperation,com.estimote.display.view.View view){ + /* View has been displayed! You can refresh the UI and inform user about it. */ } - @Override - public void onViewOperationFailed(ViewOperation show, - com.estimote.display.view.View view, String message) { - Log.d("Mirror", "Oh no!") + @Override + public void onViewOperationFailed(ViewOperation show,com.estimote.display.view.View view,String message){ + /* Oops! Something went wrong - check the message and maybe try to display the view once again! */ } }); - } -} ``` -## Documentation +# Your feedback and questions + +At Estimote we're massive believers in feedback! Here are some common ways to share your thoughts with us: + +* Posting issue/question/enhancement on [our issues page](../../../issues). +* Asking our community managers on our [Estimote SDK for Android forum](https://forums.estimote.com). -We have extensive documentation available on [Estimote Developer Portal](http://developer.estimote.com). +# Changelog -The best place to get started is with … [Intro to Estimote Mirror](http://developer.estimote.com/mirror/)! +To see what has changed in recent versions of our SDK, please visit [our releases page](../../../releases). -## "Work in progress" disclaimer +# License -The APIs are not yet considered stable and will likely change … for better, and more powerful, naturally 😇 We'll be providing detailed changelogs and migration advice as we go. +[Apache 2.0](../license.txt)