Unsplash Photo Picker

Unsplash Photo Picker is a modular and customizable Android View that allows you to quickly search Unsplash.com for free high-quality photos with just a few lines of code.

Based on Unsplash Photo Picker for Android by Unsplash, this library adds more flexibility, conveniences and customization than the original.

The original only launched an Activity for you which you had no control of, this provides you with a View you can use in your layouts.

• Unsplash Photo Picker
  • Description
  • Requirements
  • Installation
  • Usage
    • Initial Configuration
    • Quick Use
    • Xml Attributes
    • Click Listeners
    • Showing a Photo
    • Internationalization (i18n)
  • Abiding by the Unsplash API Guidelines
  • Download Sample App
  • Special Thanks
  • License

Description

This library allows you to add a fully functioning photo picker which searches free high-quality photos from Unsplash.com.

You can select multiple (or one) images and you can show any image in fullscreen.

This library will also take care of following most of the Unsplash Technical API Guidelines for you, however I am not responsible or liable if you do not follow them yourself.

See the Abiding by the Unsplash API Guidelines section for more details.

Requirements

• Min API 21 and AndroidX
• Kotlin 1.3+
• Unsplash API Access Key and Secret Key

Installation

Add the JitPack repository to your root build.gradle at the end of repositories:

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Add the dependency in your app module build.gradle file:

dependencies {
    implementation 'com.github.basshelal:UnsplashPhotoPicker:1.1.2'
}

Usage

⚠️ IMPORTANT! ⚠️

️Before you get started, you need to register as a developer on the Unsplash Developer portal. Once registered, create a new app to get an Access Key and a Secret Key.

Remember you must keep both keys secret.

Initial Configuration

You need to call UnsplashPhotoPickerConfig.init(...) in your custom Application class's onCreate(), with the required arguments.

class App : Application() {
    
    override fun onCreate() {
        super.onCreate()
        
        UnsplashPhotoPickerConfig.init(
            application = this,
            accessKey = "your access key",
            secretKey = "your secret key",
            unsplashAppName = "your app's name on Unsplash",
            isLoggingEnabled = false // optional to enable full HTTP logging, defaults to false
        )
    }
}

Quick Use

Showing the photo picker takes a few lines of code, with many customization options and listeners available, see the full list in Xml Attributes and Click Listeners

Kotlin:

    UnsplashPhotoPicker.show(this /*: Context*/ ) {
        hasSearch = true
        persistentSearch = true
        longClickSelectsPhoto = false
        clickOpensPhoto = false
        onClick = { photo,_ -> selectPhoto(photo) }
        // more customization here...
    }

Xml:

<com.github.basshelal.unsplashpicker.presentation.UnsplashPhotoPicker
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>

Xml Attributes

All xml attributes begin with photoPicker_.

For the full documentation, check out attributes.md or the UnsplashPhotoPicker class itself.

All public APIs in this library are well documented.

PhotoSize enum: thumb, small, medium, regular, large, full, raw

See the PhotoSize enum class

Click Listeners

You can listen to click events on any photo in the picker using onClickPhoto and onLongClickPhoto which are both anonymous functions (lambdas) which have the UnsplashPhoto as their first parameter and the clicked ImageView as the second parameter.

unsplashPhotoPicker.apply {
    onClickPhoto = { unsplashPhoto, imageView -> this.showPhoto(unsplashPhoto) }
    onLongClickPhoto = { unsplashPhoto, imageView -> this.selectPhoto(unsplashPhoto) }
}

Showing a Photo

You can show any UnsplashPhoto (even if you don't have an UnsplashPhotoPicker) using a couple of lines:

    PhotoShowFragment.show(
        activity /*: FragmentActivity*/,
        photo /*: UnsplashPhoto*/
    )

Internationalization (i18n)

This library is fully i18n-friendly.

Any text shown can be changed to match the language and locale with full RTL support!

Abiding by the Unsplash API Guidelines

⚠️ IMPORTANT! ⚠️

You must follow the Unsplash API Guidelines when using the Unsplash API in your application.

This application takes care of Technical Guidelines 1-3 for you however, I am not responsible or liable if you do not follow them yourself.

Below are the Technical guidelines and how this library follows and implements them.

1. All API uses must use the hotlinked image URLs returned by the API under the photo.urls properties. This applies to all uses of the image and not just search results.

This is automatically done for you courtesy of the original library, do not worry about this.

1. When your application performs something similar to a download (like when a user chooses the image to include in a blog post, set as a header, etc.), you must send a request to the download endpoint returned under the photo.links.download_location property.

When you are done with your images you must call UnsplashPhotoPicker.downloadPhotos to send the download request.

1. When displaying a photo from Unsplash, your application must attribute Unsplash, the Unsplash photographer, and contain a link back to their Unsplash profile. All links back to Unsplash should use utm parameters in the ?utm_source=your_app_name&utm_medium=referral.

This is done for you as you provide the Unsplash app name when you call UnsplashPickerConfig.init(...). This must be the name of your app on the Unsplash developer portal.

1. Your application’s Access Key and Secret Key must remain confidential. This means that they cannot be included in the client or made public. In most cases, this will require proxying the API through your own endpoint to sign the request with your keys.

This one's on you. I recommend you make a Keys.kt file containing 2 String const vals, one for the Access key and one for the Secret key by add the file to the .gitignore file so it doesn't get checked into Version Control. This solution has worked for me but be sure to test it yourself. Again, I am not responsible or liable if you mess up.

Download Sample App

Download by clicking or using the QR Code below on your device:

Special Thanks

Special Thanks to Unsplash for creating a beautiful free service with an easy to use API, seriously you guys are awesome.

Special Thanks again to Unsplash for the initial code that this library is based off of, they've very elegantly done the backend code used to perform network requests. This library would not be possible without them and without them making it open source and licensing it with the MIT License, open and free for all as this library is as well. Many thanks to them for all of this.

License

MIT License

Copyright (c) 2019 Bassam Helal

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.