Skip to content
This repository has been archived by the owner on Sep 3, 2021. It is now read-only.

Commit

Permalink
Merge branch 'master' into develop
Browse files Browse the repository at this point in the history
  • Loading branch information
catt-stefano committed Oct 20, 2017
2 parents 079644b + 672ccbb commit c432d97
Show file tree
Hide file tree
Showing 43 changed files with 1,166 additions and 96 deletions.
1 change: 1 addition & 0 deletions .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ android:
- tools # see https://github.com/travis-ci/travis-ci/issues/6040#issuecomment-219367943)
- platform-tools
- build-tools-26.0.1
- build-tools-26.0.2
- tools
- android-26
- extra-google-m2repository
Expand Down
22 changes: 22 additions & 0 deletions docs/css/nearitdocs.css
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,28 @@ a.icon-home {
/* bigger text in code elements */
code {font-size: 14px !important}

.code-switcher {
margin-bottom: -1px;
}

.code-switcher button {
background: #fff;
border: 1px solid #DDD;
color: #666;
position: relative;
}

.code-switcher button.active {
color: #222;
border-bottom: 1px solid white;
}

pre.code {
margin-top:0;
}

button:focus {outline:0;}

/* bigger text in tables */
th, td {font-size: 100% !important}

Expand Down
59 changes: 37 additions & 22 deletions docs/custom-bkg-notification.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,14 @@

## Styling options
You can set your own icon for the location-based notifications and the push notifications with the methods:
```java
<div class="code-java">
NearItManager.getInstance().setProximityNotificationIcon(R.drawable.ic_my_location_notification);
NearItManager.getInstance().setPushNotificationIcon(R.drawable.ic_my_push_notification);
```
</div>
<div class="code-kotlin">
NearItManager.getInstance().setProximityNotificationIcon(R.drawable.ic_my_location_notification)
NearItManager.getInstance().setPushNotificationIcon(R.drawable.ic_my_push_notification)
</div>

## Custom Service
To handle complex use cases, you can write your own IntentService by subclassing the built-in one.
Expand All @@ -21,28 +25,39 @@ This JobIntentService (not to be declared in the app manifest), creates the back
By extending NearBackgroundJobIntentService you can customize the app background behavior.

In the `onHandleWork` of the custom IntentService:
```java
<div class="code-java">
@Override
protected void onHandleWork(@NonNull Intent intent) {
/*
Do whatever you want with the intent, but be aware that, depending on the target,
this might be executed in a jobservice and background limitations apply.
To notify it to the user with a system notification, call
super.sendSimpleNotification(intent);
this method also sends the proper tracking information to our servers.
If you want to completely customize the user experience, you should implement your logic here.
You may want to use this method:
NearUtils.parseCoreContents(intent, coreContentListener); // to get casted content in the listener callback methods
IMPORTANT
If you are overriding the default notification mechanism, remember to track the recipe as notified with:
TrackingInfo trackingInfo = intent.getParcelableExtra(NearItIntentConstants.TRACKING_INFO);
NearItManager.getInstance().sendTracking(trackingInfo, Recipe.NOTIFIED_STATUS);
*/
protected void onHandleWork(@NonNull Intent intent) {
// Do whatever you want with the intent, but be aware that, depending on the target,
// this might be executed in a jobservice and background limitations apply.<br>
// To notify it to the user with a system notification, call
// super.sendSimpleNotification(intent);
// this method also sends the proper tracking information to our servers.<br>
// If you want to completely customize the user experience, you should implement your logic here.
// You may want to use this method:
// NearUtils.parseCoreContents(intent, coreContentListener); // to get casted content in the listener callback methods<br>
// IMPORTANT
// If you are overriding the default notification mechanism, remember to track the recipe as notified with:
// TrackingInfo trackingInfo = intent.getParcelableExtra(NearItIntentConstants.TRACKING_INFO);
// NearItManager.getInstance().sendTracking(trackingInfo, Recipe.NOTIFIED_STATUS);
}
```
</div>
<div class="code-kotlin">
override fun onHandleWork(intent: Intent) {
// Do whatever you want with the intent, but be aware that, depending on the target,
// this might be executed in a jobservice and background limitations apply.<br>
// To notify it to the user with a system notification, call
// super.sendSimpleNotification(intent)
// this method also sends the proper tracking information to our servers.<br>
// If you want to completely customize the user experience, you should implement your logic here.
// You may want to use this method:
// NearUtils.parseCoreContents(intent, coreContentListener) // to get casted content in the listener callback methods<br>
// IMPORTANT
// If you are overriding the default notification mechanism, remember to track the recipe as notified with:
// val trackingInfo: TrackingInfo = intent.getParcelableExtra(NearItIntentConstants.TRACKING_INFO)
// NearItManager.getInstance().sendTracking(trackingInfo, Recipe.NOTIFIED_STATUS)
}
</div>

Then add your custom IntentService to the manifest
```xml
Expand Down
83 changes: 63 additions & 20 deletions docs/in-app-content.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,36 +2,57 @@

After an user **taps on a notification**, you will receive content through an intent to your app launcher activity.
If you want to just check if the intent carries NearIT content use this method:
```java

<div class="code-java">
boolean hasNearItContent = NearUtils.carriesNearItContent(intent);
```
</div>
<div class="code-kotlin">
var hasNearItContent = NearUtils.carriesNearItContent(intent)
</div>
To extract the content from an intent use the utility method:
```java
<div class="code-java">
NearUtils.parseCoreContents(intent, coreContentListener);
```

</div>
<div class="code-kotlin">
NearUtils.parseCoreContents(intent, coreContentListener)
</div>

If you want to customize the behavior of background notification see [this page](custom-bkg-notification.md).

## Beacon Interaction Content
Beacon interaction (beacon ranging) is a peculiar trigger that works only when your app is in the foreground.<br>
To receive this kind of content set a **proximity listener** with the method:
```java
<div class="code-java">
{
...
NearItManager.getInstance().addProximityListener(this);
// remember to remove the listener when the object is being destroyed with
// NearItManager.getInstance().removeProximityListener(this);
...
}

@Override
public void foregroundEvent(Parcelable content, TrackingInfo trackingInfo) {
// handle the event
// To extract the content and to have it automatically casted to the appropriate object type
NearUtils.parseCoreContents(content, trackingInfo, coreContentListener);
}
```
}
</div>
<div class="code-kotlin">
{
...
NearItManager.getInstance().addProximityListener(this)
// remember to remove the listener when the object is being destroyed with
// NearItManager.getInstance().removeProximityListener(this)
...
}
override fun foregroundEvent(content: Parcelable, trackingInfo: TrackingInfo) {
// handle the event
// To extract the content and to have it automatically casted to the appropriate object type
NearUtils.parseCoreContents(content, trackingInfo, coreContentListener)
}
</div>


**Warning:** For this kind of content you will need to write the code for **Trackings** and to eventually show an **In-app notification**.


Expand All @@ -46,8 +67,8 @@ Usually the SDK tracks those events automatically, but if you write custom code


You can track **default or custom events** using the "**sendTracking**" method:
```java

<div class="code-java">
// notified - notification received
NearItManager.getInstance().sendTracking(trackingInfo, Recipe.NOTIFIED_STATUS);

Expand All @@ -56,7 +77,17 @@ NearItManager.getInstance().sendTracking(trackingInfo, Recipe.ENGAGED_STATUS);

// custom recipe event
NearItManager.getInstance().sendTracking(trackingInfo, "my awesome custom event");
```
</div>
<div class="code-kotlin">
// notified - notification received
NearItManager.getInstance().sendTracking(trackingInfo, Recipe.NOTIFIED_STATUS)

// engaged - notification tapped
NearItManager.getInstance().sendTracking(trackingInfo, Recipe.ENGAGED_STATUS)

// custom recipe event
NearItManager.getInstance().sendTracking(trackingInfo, "my awesome custom event")
</div>

## Content Objects

Expand All @@ -77,12 +108,19 @@ Here are the public fields for every other one:
- `question` returns the feedback request string
- `getRecipeId()` returns the recipeId associated with the feedback (you'll need it for answer it)
To give a feedback call this method:
```java

<div class="code-java">
// rating must be an integer between 1 and 5, and you can set a comment string.
NearItManager.getInstance().sendEvent(new FeedbackEvent(feedback, rating, "Awesome"));
// the sendEvent method is available in 2 variants: with or without explicit callback handler. Example:
NearItManager.getInstance().sendEvent(new FeedbackEvent(...), responseHandler);
```
</div>
<div class="code-kotlin">
// rating must be an integer between 1 and 5, and you can set a comment string.
NearItManager.getInstance().sendEvent(FeedbackEvent(feedback, rating, "Awesome"))
// the sendEvent method is available in 2 variants: with or without explicit callback handler. Example:
NearItManager.getInstance().sendEvent(FeedbackEvent(...), responseHandler)
</div>

- `Coupon` with the following getters and fields:
- `getTitle()` returns the coupon title
Expand All @@ -106,19 +144,24 @@ NearItManager.getInstance().sendEvent(new FeedbackEvent(...), responseHandler);

We handle the complete emission and redemption coupon cycle in our platform, and we deliver a coupon content only when a coupon is emitted (you will not be notified of recipes when a profile has already received the coupon, even if the coupon is still valid).
You can ask the library to fetch the list of all the user current coupons with the method:
```java
<div class="code-java">
NearItManager.getInstance().getCoupons(new CouponListener() {
@Override
public void onCouponsDownloaded(List<Coupon> list) {

}

@Override
public void onCouponDownloadError(String s) {

}
}
});
```
</div>
<div class="code-kotlin">
NearItManager.getInstance().getCoupons(object : CouponListener {
override fun onCouponsDownloaded(coupons: MutableList<Coupon>?) {
}
override fun onCouponDownloadError(s: String) {
}
})
</div>
The method will also return already redeemed coupons so you get to decide to filter them if necessary.


14 changes: 10 additions & 4 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,12 +42,18 @@ You can find your API key on <a href="https://go.nearit.com/" target="_blank">**
The SDK **initialization is done automatically** and handles the task of syncing the recipes with our servers when your app starts up.
<br>However, if you need to sync the recipes configuration more often, you can call this method:

```java
<div class="code-java">
NearItManager.getInstance().refreshConfigs();
```
</div>
<div class="code-kotlin">
NearItManager.getInstance().refreshConfigs()
</div>

If you need feedback on whether the refresh was successful or not, you can use this other version of the method:

```java
<div class="code-java">
NearItManager.getInstance().refreshConfigs(recipeRefreshListener);
```
</div>
<div class="code-kotlin">
NearItManager.getInstance().refreshConfigs(recipeRefreshListener)
</div>
39 changes: 39 additions & 0 deletions docs/js/extra.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
$(function(){

$('.code-java').replaceWith(function() {
return $('<div class="code-switcher"> <button class="tab-java" onclick="switchCode(0)">Java</button> <button class="tab-kotlin" onclick="switchCode(1)">Kotlin</button> </div><pre class="code java"><code>' + this.innerHTML + '</code></pre>');
});

$('.code-kotlin').replaceWith(function() {
return $('<pre class="code kotlin"><code>' + this.innerHTML + '</code></pre>');
});

switchCode(0);

})

function switchCode(item) {

// hide all code blocks
$('.code').hide();

// show selected code blocks and change selected tab
switch (item) {
case 0:
$('.java').show();
$('.tab-java').addClass('active')
$('.tab-kotlin').removeClass('active')
break;
case 1:
$('.kotlin').show();
$('.tab-kotlin').addClass('active')
$('.tab-java').removeClass('active')
break;
default:
$('.java').show();
$('.tab-java').addClass('active')
$('.tab-kotlin').removeClass('active')
break;
}

}
9 changes: 7 additions & 2 deletions docs/location-based-notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,16 @@ If you are also manually including ACCESS_COARSE_LOCATION in your manifest pleas

When you want to start the radar for **geofences and beacons** call this method:

```java
<div class="code-java">
// call this when you are given the proper permission for scanning (ACCESS_FINE_LOCATION)
NearItManager.getInstance().startRadar();
// to stop the radar call the method nearItManager.stopRadar()
</div>
<div class="code-kotlin">
// call this when you are given the proper permission for scanning (ACCESS_FINE_LOCATION)
NearItManager.getInstance().startRadar()
// to stop the radar call the method nearItManager.stopRadar()
```
</div>

The SDK creates a system notification for every background recipe. On the notification tap, your launcher activity will start.
To learn how to deal with in-app content once the user taps on the notification, see this [section](in-app-content.md).
Expand Down
15 changes: 9 additions & 6 deletions docs/logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,13 @@ If you are scanning beacons you have probably noticed the flood of logging messa
![logfilter](logfilter.png "")

The SDK itself produces logs for various events. Without specific configuration it uses the Android system logs, but you can set your own logger with the method:
```java
<div class="code-java">
NearLog.setLogger(new NearLogger() {

// various methods to override

});
```
// various methods to override
});
</div>
<div class="code-kotlin">
NearLog.setLogger(object : NearLogger {
// various methods to override
})
</div>
17 changes: 13 additions & 4 deletions docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,24 @@ To help with testing, you can manually trigger a recipe.
The `NearItManager` object has a getter for the `RecipesManager`.
With this object you can get the list of recipes with the method:

```java
<div class="code-java">
NearItManager.getInstance().getRecipesManager().getRecipes()
```
</div>
<div class="code-kotlin">
NearItManager.getInstance().recipesManager.recipes
</div>

Once you pick the recipe you want to test, use this method to trigger it:

```java
<div class="code-java">
String id = recipe.getId();
NearItManager.getInstance().getRecipesManager().processRecipe(id);
```
</div>
<div class="code-kotlin">
val id = recipe.getId()
NearItManager.getInstance().recipesManager.processRecipe(id)
</div>

## Creating a Tester Audience

If you need to test some content, but just with some testers, you can use the profiling features and create actual recipes, selecting the proper segment.
Expand Down
Loading

0 comments on commit c432d97

Please sign in to comment.