- Overview
- Main features
- Setup environment
- Configure credentials
- Sample code
- Custom dictionary
- Codestyle
- Code analysis
- Public API changes tracking
- Testing
- Offline integration tests
- Complex checks run
- Documentation
- Third-party SDKs license
- Contributing
- Versioning
The Mapbox Search SDK is a developer toolkit to add location search on mobile devices. With the same speed and scale of the Mapbox Search API, the SDK is built specifically for on-demand and local search use cases, like ride-share, food delivery, and store finders apps. Whether your users are trying to find a place among the vast amount of data on a global map, or to find the exact location of a venue a few miles down the road, the Search SDK provides location search for countries all over the globe, in many different languages.
Previously, implementing search into your application required custom tuning with every API request to set a language, location biasing, and result types. There was no pre-built UI and no option for a user to see their search history, or save favorites.
The Mapbox Search SDK allows you to drop pre-tuned search into your application, removing the complexity of API configuration, while still giving you control to customize. It ships with an optional UI framework, or you can build a completely custom implementation with your own UI elements by using the core library. The Search SDK is pre-configured for autocomplete, local search biasing, and includes new features like category search, search history, and search favorites.
- Easy-to-use pre-tuned search options to integrate search into your app quickly.
- Local search for a specific address or POI
- Pre-configured and customizable category search for popular categories like cafes, ATMs, hotels, and gas stations.
- Offline search (private beta)
- Address Autofill
- On-device user search history
- On-device favorites
- Import/export customer data with your own protocols
- Provide you own persistent providers for customer data like History or Favorites
Visit Search SDK documentation page for more information.
Below are listed the versions on which everything is going to work fine. Other versions might work as well but wasn't tested yet.
- Android Studio
- Java 11
Before installing the SDK, you will need to gather two pieces of sensitive information from your Mapbox account. If you don't have a Mapbox account: sign up and navigate to your Account page. You'll need:
- A public access token: From your account's tokens page, you can either copy your default public token or click the Create a token button to create a new public token.
- A secret access token with the
Downloads:Readscope.
Export your public token as an environment variable MAPBOX_ACCESS_TOKEN and your secret access token as an environment variable SDK_REGISTRY_TOKEN. Alternatively, you can provide those credentials as project properties.
Examples for Mapbox Search SDK for Android are available here.
Don't forget to add custom dictionary file located at AndroidStudio/dictionary.dic to Android Studio: Preferences -> Editor -> Spelling -> Add custom dictionaries. Update this file with correct words that are not contained in the default dictionary of Android Studio.
We use ktlint for checking Kotlin codestyle and formatting.
To run ktlint checks locally:
cd MapboxSearch
./gradlew :sdk:ktlint
To run ktlint formatter:
./gradlew :sdk:ktlintFormat
Also we have custom codestyle settings for XML. To apply those settings, please, select AndroidStudio/code_style.xml file in Android Studio: Preferences -> Editor -> Code style -> XML -> "gear button" -> Import Scheme.
For any resource name we use prefix mapbox_search_sdk or MapboxSearchSdk depending on resource type according to official Google recommendations: Android library creation recommendations
We use detekt as static code analyzer.
To run detekt locally:
cd MapboxSearch
./gradlew :sdk:detekt
We use binary-compatibility-validator and Metalava for tracking binary and source compatibility of the APIs we ship.
Also we use special Gradle task to generate public.xml file, which helps us track changes in public API of Android values/ resources. Please note that not every values/ resource is tracked, so if you want to add extra resources under the radar, please, specify file contatining these resources manually in mentioned Gradle task.
To check whether your change affects public API, run public-api.sh script with --check argument:
cd MapboxSearch
../scripts/public-api.sh --check
If your change implies changes to the public API, run public-api.sh script with --update argument:
cd MapboxSearch
../scripts/public-api.sh --update
If you want to update Metalava, please, use update_metalava.sh script. This scripts places the latest metalava.jar into MapboxSearch/metalava folder and prints out its deps:
./scripts/update_metalava.sh
Cloning… Done
Building… Done
Dependencies:
com.android.tools.external.org-jetbrains:uast:27.2.0-alpha11
com.android.tools.external.com-intellij:kotlin-compiler:27.2.0-alpha11
com.android.tools.external.com-intellij:intellij-core:27.2.0-alpha11
com.android.tools.lint:lint-api:27.2.0-alpha11
com.android.tools.lint:lint-checks:27.2.0-alpha11
com.android.tools.lint:lint-gradle:27.2.0-alpha11
com.android.tools.lint:lint:27.2.0-alpha11
com.android.tools:common:27.2.0-alpha11
com.android.tools:sdk-common:27.2.0-alpha11
com.android.tools:sdklib:27.2.0-alpha11
org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.4.30
org.jetbrains.kotlin:kotlin-reflect:1.4.30
org.ow2.asm:asm:8.0
org.ow2.asm:asm-tree:8.0
Copy and paste (update) the new deps into gradle/metalava-dependencies.gradle
Japicmp is a library, that helps you to determine the differences between the Java .class files, contained in two given .jar archives. Also, this library provides HTML reports with detailed information about each class/method that has been changed.
To use this tool, follow this steps:
- Uncomment
include ':gradle:japicmp'line inMapboxSearch/settings.gradle; - Open
MapboxSearch/gradle/japicmp/build.gradleand make sure:baselinetargets to the latestmapbox-search-android(ormapbox-search-android-ui) artifact;latesttargets toproject(path: ':sdk', configuration: 'default')(orproject(path: ':ui', configuration: 'default')).
- Run
./gradlew :gradle:japicmp:japicmptask. If breaking changes have been found, you'll see Gradle failure and a link to HTML report in the output.
We use Kotlin Test DSL for unit tests. Kotlin Test DSL provides human-readable DSL and is based on JUnit 5 dynamic tests. To run unit tests use the following commands:
./gradlew :sdk:testReleaseUnitTest
./gradlew :ui:testReleaseUnitTest
./gradlew :sdk-common:testReleaseUnitTest
Search SDK also contains a bunch of instrumentation and UI tests. To run them, please, use the following command:
./gradlew connectedAndroidTest mergeAndroidReports --continue
We use pitest for mutation testing. To run pitest, execute the following commands:
cd MapboxSearch
./gradlew :sdk:pitestDebug
You can find report at MapboxSearch/sdk/build/reports.
To run offline integration tests, please, make sure your MAPBOX_ACCESS_TOKEN has offline_search feature flag enabled. As for now, offline functionality (including offline tests) is in a private beta and available to selected customers only.
To run all checks and unit tests locally, execute local_checks.sh script:
./scripts/local_checks.sh
Add --runInstrumentationTests flag to also run instrumentation and UI tests. In this case only one running emulator should be available via adb.
Public Search SDK documentation.
We use dokka for top level public classes overview. To generate docs for all modules use the following command:
./scripts/generate_docs.sh
You can find generated docs in MapboxSearch/build/generated-docs/ directory.
Project's additional 3rd-party licences, used by the SDK module and by the UI module, are stored here.
To update license file, please, run python scripts/license-generate.py from the project's root directory. To validate current license file, please, run python scripts/license-validate.py from the project's root directory.
We welcome feedback and code contributions!
If you found a bug in Android SDK open a github issue. General feedback is welcoming in the search-sdk repo.
Examples of behavior that contributes to creating a positive environment include:
- Using welcoming and inclusive language.
- Being respectful of differing viewpoints and experiences.
- Gracefully accepting constructive criticism.
- Focusing on what is best for the community.
- Showing empathy towards other community members.
We recommend reading this blog post from Github on writing great PRs..
We use SemVer for versioning.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent