wingu Android SDK
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE
api
docs
releases/com/github/Speicher210/wingu-android-sdk
.gitignore
LICENSE

README.md

Platform Version License API docs

wingu-android-sdk

wingu-android-sdk is an SDK for wingu.de service. This framework will allow you to find nearby beacons and geofences at user's location, and display content attached to those channels. It also supports discovering content via QR codes and NFC tags.

Table of contents

  1. Installation
  2. Requirements
  3. Listening for nearby channels
  4. Documentation
  5. About wingu
  6. Authors
  7. License

1. Installation

In build.gradle of your application module add this:

android {
  compileSdkVersion 27

  defaultConfig {
    // wingu SDK requires `minSdkVersion >= 21` and `targetSdkVersion <= 27`.
    minSdkVersion 21
    targetSdkVersion 27
    multiDexEnabled true
  }
}

repositories {
  maven { url "https://maven.google.com" }
  maven { url "https://jitpack.io" }
  maven { url "https://github.com/wingu-GmbH/wingu-android-sdk/raw/master/releases" }
}

dependencies {
  implementation 'com.github.Speicher210.wingu-android-sdk:sdk:3.6.0'
  implementation 'com.github.Speicher210.wingu-android-sdk:component-video:3.6.0' // optional
  implementation 'com.github.Speicher210.wingu-android-sdk:qrcodescanner:3.6.0' // optional
}

If you are using Kotlin standard library, Support Libraries, Google Play Services or have issues with dependencies, read dependency management.

Initialize wingu SDK in your Application subclass:

override fun onCreate() {
    super.onCreate()
    WinguSDKBuilder.with(this, YOUR_WINGU_API_KEY)
//      .registerComponent(..) // optionally activate maps & video components
        .build()
}

For start, you can use WinguSDKBuilder.DEMO_APP_ID key.

2. Requirements

To be able to listen for nearby channels (iBeacons and geofences) you need to have:

  • runtime LOCATION permission (on Android 6+; either ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION)
  • Bluetooth on
  • location services on
  • Google Play services

You can check this on your own, or use a PrerequisitesChecker class, for example in your main activity:

private val WINGU_SDK_PREREQUISITES_REQUEST = 100

override fun onStart() {
    super.onStart()
    if (PrerequisitesChecker.checkWithDefaultDialogs(this, WINGU_SDK_PREREQUISITES_REQUEST)) {
        // all prerequisites are met
        listenForNearbyChannels()
    }
    // if `checkWithDefaultDialogs` above returned `false`,
    // dialogs are shown to resolve any issues,
    // and results are returned in `onActivityResult`
}

override fun onStop() {
    stopListeningForNearbyChannels()
    super.onStop()
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == WINGU_SDK_PREREQUISITES_REQUEST) {
        val results = PrerequisitesChecker.getResolveResults(data)
        if (results != null && results.failed.isEmpty()) {
            listenForNearbyChannels()
        } else {
            Log.e("wingu", "Could not get ResolveResults or some failed")
        }
    }
}

3. Listening for nearby channels

Once you have all the prerequisites, you can listen for nearby channel events. Using NearbyChannelObserver you can be notified for example when you enter a geofence zone, or go out of beacon range.

private var channelsSubscription: Subscription? = null

private fun listenForNearbyChannels() {
    channelsSubscription?.unsubscribe()
    channelsSubscription = WinguSDK.getInstance()
        .getNearbyChannelObserver()
        .getChannelEvents()
        .subscribe(
            { channelEvents -> Log.d("wingu", "$channelEvents") },
            { throwable -> Log.e("wingu", "Could not get nearby channels", throwable) }
        )
}

private fun stopListeningForNearbyChannels() {
    channelsSubscription?.unsubscribe()
    channelsSubscription = null
}

Alternatively, you can fetch all channels that are nearby at any given moment:

val nearbyChannels = WinguSDK.getInstance().getNearbyChannelObserver().getCurrentNearbyChannels()

Finally, you can display content of selected channel:

private fun onChannelClicked(channel: Channel) {
    val intent = ChannelDetailsActivity.newInstance(this, channel, channel.name)
    startActivity(intent)
}

If you used WinguSDKBuilder.DEMO_APP_ID in the first step, you can launch the Android Emulator and set latitude to 37.422 and longitude to -122.084. Within a few seconds you will receive your first channel event. If you change the location (for example set the latitude to 38.422) you will receive a LOST event, and the content will no longer be accessible. Note: due to limitations in the Emulator, it's not possible to receive iBeacon or geofence events when the app is in background.

4. Documentation

5. About wingu

This is a wingu open source project. With wingu platform, API and SDK it is easier then ever to use proximity technologies in new and exciting ways, such as creating a simple app or adding proximity functionality to your existing application. For more information check out: https://www.wingu.de/en/developer/ or start a free trail at https://wingu-portal.de/register.

6. Authors

Android Developers @ wingu GmbH

Mateusz
Wiktor

7. License

wingu-android-sdk is available under the Apache 2.0 license. See the LICENSE file for more info.