organicmaps/api-android
13
Fork 0
Code Issues5 Pull requests Projects Releases Wiki Activity Actions

MAPS.ME rebranding

Browse source
This commit is contained in:
Alex Zolotarev 2014-07-19 15:03:01 +03:00
parent 222a3c019c
commit bfc577559b
7 changed files with 34 additions and 187 deletions

175
README.html
View file

@ -1,175 +0,0 @@
<h1>MapsWithMe Android API: Getting Started</h1>
<h2>Introduction</h2>
<p>MapsWithMe Android API (hereinafter referred to as <em>&quot;API Library&quot;</em> or just <em>&quot;library&quot;</em>)
provides interface for client application to perform next tasks:</p>
<ul>
<li>Show one or more points on offline map of <a href="http://mapswith.me/" title="MapsWithMe">MapsWithMe Application</a></li>
<li>Come back to the client application after selecting specific point on the map, by sending <a href="http://developer.android.com/reference/android/app/PendingIntent.html" title="PendingIntent">PendingIntent</a> with point data when user asks for more information by pressing &quot;More Info&quot; button in MapsWithMe Application</li>
<li>Map screen branding : your application&#39;s icon and name (or custom title) will be placed at the top.</li>
</ul>
<p>Thus, you can provide <strong>two way communication between your application and MapsWithMe</strong>,
using MapsWithMe to show points of interest (POI) and providing more information in your app.</p>
<p>Please refer to <a href="sample-app-capitals" title="Api Source Code">sample application</a> for demo.</p>
<h2>Prerequisites</h2>
<p>It is supposed that you are familiar with Android Development, and you have Android SDK and Eclipse (or another IDE of your choice) installed.
You should be familiar with concept of <a href="http://developer.android.com/guide/components/intents-filters.html" title="Intents and Intent Filters">Intents</a>, <a href="http://developer.android.com/tools/projects/index.html#LibraryProjects" title="Android Library Project">library projects</a>, and <a href="http://developer.android.com/reference/android/app/PendingIntent.html" title="PendingIntent">PendingIntents</a> (recommended) as well.
Your application must target at least <em>android sdk version 7</em>.</p>
<h2>Integration</h2>
<p>First step is to clone <a href="https://github.com/mapswithme/api-android" title="GitHub Repository">repository</a> or download it as an archive.</p>
<p>When your are done you find two folders: <em>lib</em> and <em>sample-app-capitals</em>. First one is a library project that you should add to your project.
You don&#39;t need any additional permissions in your AndroidManifest.xml to use API library, so you can write real code straight away, calling for different <code>MapsWithMeApi</code> methods (more details below). </p>
<h2>Classes Overview and HOW TO</h2>
<p>Core classes you will work with are:</p>
<ul>
<li><a href="lib/src/com/mapswithme/maps/api/MapsWithMeApi.java" title="MapsWithMeApi.java">com.mapswithme.maps.api.MapsWithMeApi</a> - static class with methods such as <code>showPointOnMap(Activity, double, double, String)</code> etc.</li>
<li><a href="lib/src/com/mapswithme/maps/api/MWMPoint.java" title="MWMPoint.java">com.mapswithme.maps.api.MWMPoint</a> - model of POI, includes lat, lon, name, and id data.</li>
<li><a href="lib/src/com/mapswithme/maps/api/MWMResponse.java" title="MWMResponse.java">com.mapswithme.maps.api.MWMResponse</a> - helps you to extract response from MapsWithMe by applying <code>MWMResponse.extractFromIntent(Intent)</code> to Intent. Contains MWMPoint data.</li>
</ul>
<h3>Show Points on the Map</h3>
<p>The simplest usage:</p>
<pre><code>public class MyPerfectActivity extends Activity {
...
void showSomethingOnTheMap(SomeDomainObject arg)
{
// Do some work, create lat, lon, and name for point
final double lat = ...;
final double lon = ...;
final String name = ...;
// Ask MapsWithMe to show the point
MapsWithMeApi.showPointOnMap(this, lat, lon, name);
}
...
}
</code></pre>
<p>For multiple points use <a href="lib/src/com/mapswithme/maps/api/MWMPoint.java" title="MWMPoint.java">MWMPoint</a> class:</p>
<pre><code>void showMultiplePoints(List&lt;SomeDomainObject&gt; list)
{
// Convert objects to MMWPoints
final MWMPoint[] points = new MWMPoint[list.length];
for (int i = 0; i &lt; list.size; i++)
{
// Get lat, lon, and name from object and assign it to new MMWPoint
points[i] = new MWMPoint(lat, lon, name);
}
// Show all point on the map, you could also provide some title
MapsWithMeApi.showPointsOnMap(this, &quot;Look at my points, my points are amazing!&quot;, points);
}
</code></pre>
<h3>Ask MapsWithMe to Call my App</h3>
<p>We support PendingIntent interaction (just like Android native
NotificationManager does). You should specify ID for each point to
distinguish it later, and PentingIntent that MapsWithMe will send back to
your application when user press &quot;More Info&quot; button :</p>
<pre><code>// Here is how to pass points with ID ant PendingIntent
void showMultiplePointsWithPendingIntent(List&lt;SomeDomainObject&gt; list, PendingIntent pendingIntent)
{
// Convert objects to MMWPoints
final MWMPoint[] points = new MWMPoint[list.length];
for (int i = 0; i &lt; list.size; i++)
{
// ||
// ||
// \/
// Now you should specify string ID for each point
points[i] = new MWMPoint(lat, lon, name, id);
}
// Show all points on the map, you could also provide some title
MapsWithMeApi.showPointsOnMap(this, &quot;This title says that user should choose some point&quot;, pendingIntent, points);
}
//Code below shows general way to extract response data
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Handle intent you specified with PandingIntent
// Now it has additional information (MWMPoint).
handleIntent(getIntent());
}
@Override
protected void onNewIntent(Intent intent)
{
super.onNewIntent(intent);
// if defined your activity as &quot;SingleTop&quot;- you should use onNewIntent callback
handleIntent(intent);
}
void handleIntent(Intent intent)
{
// Apply MWMResponse extraction method to intent
final MWMResponse mwmResponse = MWMResponse.extractFromIntent(this, intent);
// Here is your point that user selected
final MWMPoint point = mwmResponse.getPoint();
// Now, for instance you can do some work depending on point id
processUserInteraction(point.getId());
}
</code></pre>
<h2>FAQ</h2>
<h4>How should I detect if user has MapsWithMe installed?</h4>
<p><code>MapsWithMeApi.isMapsWithMeInstalled(Context)</code> will return <code>true</code> if user has <em>Lite</em> or <em>Pro</em> version that supports API call installed.</p>
<h4>Which versions of MapsWithMe support API calls?</h4>
<p>Both <em>Lite</em> and <em>Pro</em> versions since 2.4.0 are support API calls.</p>
<h4>What will happen if I call for <code>MapsWithMeApi.showPoint()</code> but MapsWithMe application is not installed?</h4>
<p>Nothing serious. API library will show simple dialog with gentle offer to download MapsWithMe. You can see how it looks like below. <img src="site/images/dlg.png" alt="Please install us"></p>
<h4>If user has both <em>Lite</em> and <em>Pro</em> versions which one will be called?</h4>
<p>MapsWithMe Pro will serve your request in the case if both <em>Lite</em> and <em>Pro</em> versions installed. </p>
<h2>Sample Code and Application</h2>
<ul>
<li><a href="http://play.google.com/store/apps/details?id=com.mapswithme.capitals" title="Api Demo .apk">Sample Application at Google Play</a></li>
<li><a href="sample-app-capitals" title="Api Source Code">Sample Application Source Code</a></li>
</ul>
<h2>Support</h2>
<p>If you have any questions please email to <a href="mailto:api@mapswith.me" title="MapsWithMe Support Contact">api@mapswith.me</a>.</p>
<hr>
<h2>API Code License</h2>
<p>Copyright (c) 2013, MapsWithMe GmbH
All rights reserved.</p>
<p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
<ul>
<li>Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.</li>
<li>Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.</li>
</ul>
<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS &quot;AS IS&quot; AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>

7
README.md
View file

@ -1,6 +1,9 @@
# MapsWithMe Android API: Getting Started
# maps.me Android API: Getting Started
## Introduction
NOTE: We have changed the name of our maps from MapsWithMe to maps.me, but left all references below unchanged.
MapsWithMe Android API (hereinafter referred to as *"API Library"* or just *"library"*)
provides interface for client application to perform next tasks:
@ -145,7 +148,7 @@ If you have any questions please email to [api@mapswith.me][linkSupport].
-------------------------------------------------------------------------------
## API Code License
Copyright (c) 2013, MapsWithMe GmbH
Copyright (c) 2014, MapsWithMe GmbH
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

10
lib/res/values/strings.xml
View file

@ -1,9 +1,9 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="mwm_should_be_installed">Offline maps are required to proceed. We have partnered with MapsWithMe to provide you with offline maps of the entire world.\nTo continue please download the app:</string>
<string name="down_lite">Download MapsWithMe Lite (free)</string>
<string name="down_pro">Download MapsWithMe Pro</string>
<string name="mwm_should_be_installed">Offline maps are required to proceed. We have partnered with maps.me to provide you with offline maps of the entire world.\nTo continue please download the app:</string>
<string name="down_lite">Download maps.me Lite (free)</string>
<string name="down_pro">Download maps.me Pro</string>
<string name="url_pro">http://mapswith.me/get</string>
<string name="url_lite">http://mapswith.me/app</string>
<string name="url_pro">http://maps.me/get</string>
<string name="url_lite">http://maps.me/app</string>
</resources>

2
sample-app-capitals/AndroidManifest.xml
View file

@ -28,7 +28,7 @@
<uses-sdk
android:minSdkVersion="7"
android:targetSdkVersion="17" />
android:targetSdkVersion="19" />
<application
android:allowBackup="true"

19
sample-app-capitals/build.gradle Normal file
View file

@ -0,0 +1,19 @@
apply plugin: 'android'
android {
// Define these properties in the gradle.properties file in the root project folder
compileSdkVersion propTargetSdkVersion.toInteger()
buildToolsVersion propBuildToolsVersion
defaultConfig {
minSdkVersion propMinSdkVersion.toInteger()
targetSdkVersion propTargetSdkVersion.toInteger()
}
sourceSets.main {
manifest.srcFile 'AndroidManifest.xml'
java.srcDirs = ['src']
res.srcDirs = ['res']
}
}

2
sample-app-capitals/project.properties
View file

@ -11,5 +11,5 @@
#proguard.config=${sdk.dir}/tools/proguard/proguard-android.txt:proguard-project.txt
# Project target.
target=android-17
target=android-19
android.library.reference.1=../lib

6
sample-app-capitals/res/values/strings.xml
View file

@ -1,9 +1,9 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="app_name">MapsWithMeCapitals</string>
<string name="show_all">Show All Capitals with MapsWithMe</string>
<string name="open_with_mapswithme">Open With MapsWithMe</string>
<string name="app_name">maps.me capitals</string>
<string name="show_all">Show all capitals with maps.me</string>
<string name="open_with_mapswithme">Open with maps.me</string>
<string name="name">Name:</string>
<string name="alternative_names">Alternative names:</string>
<string name="lat">Lat:</string>