Skip to content

Commit db505bb

Browse files
ahnvahnv
authored
Update README.md
1 parent 157ddeb commit db505bb

File tree

1 file changed

+215
-65
lines changed

1 file changed

+215
-65
lines changed

‎README.md‎

Lines changed: 215 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
[<img width="250" alt="ImageKit.io" src="https://raw.githubusercontent.com/imagekit-developer/imagekit-javascript/master/assets/imagekit-light-logo.svg"/>](https://imagekit.io)
2+
13
# ImageKit.io Android SDK
24

35
[![Release](https://jitpack.io/v/imagekit-developer/imagekit-android.svg)](https://jitpack.io/#imagekit-developer/imagekit-android)
@@ -9,14 +11,17 @@
911
Android SDK for [ImageKit.io](https://imagekit.io) which implements client-side upload and URL generation for use inside an Android application.
1012

1113
ImageKit is a complete image optimization and transformation solution that comes with an [image CDN](https://imagekit.io/features/imagekit-infrastructure) and media storage. It can be integrated with your existing infrastructure - storages like AWS S3, web servers, your CDN and custom domain names, allowing you to deliver optimized images in minutes with minimal code changes.
12-
Android client for Imagekit Integration
1314

14-
## Requirements
15-
The library requires Android version 5.0.0 (API level 21 - Lollipop) or above.
15+
ImageKit Android SDK allows you to use real-time [image resizing](https://docs.imagekit.io/features/image-transformations), [optimization](https://docs.imagekit.io/features/image-optimization), and [file uploading](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload) in the client-side.
1616

1717
## Installation
18+
19+
### Requirements
20+
The library requires Android version 5.0.0 (API level 21 - Lollipop) or above.
21+
22+
### Installation
1823
In your root build.gradle file, add:
19-
```xml
24+
```gradle
2025
allprojects {
2126
repositories {
2227
...
@@ -26,14 +31,18 @@ allprojects {
2631
```
2732

2833
In the module build.gradle file, add:
29-
```xml
34+
```gradle
3035
implementation 'com.github.imagekit-developer:imagekit-android:<VERSION>'
3136
```
3237

33-
## Initialization
34-
You need to initialize the sdk by providing the application context, `publicKey` and the `urlEndpoint`. You can do this either in your application or launcher activity. This needs to be called before any other function in the SDK or else an exception would be thrown.
38+
## Usage
39+
40+
### Initialization
41+
`urlEndpoint` is the required parameter. You can get the value of URL-endpoint from your ImageKit dashboard - https://imagekit.io/dashboard#url-endpoints.
42+
43+
`publicKey` and `authenticationEndpoint` parameters are optional and only needed if you want to use the SDK for client-side file upload. You can get these parameters from the developer section in your ImageKit dashboard - https://imagekit.io/dashboard#developers.
3544

36-
`authenticationEndpoint` is only required if you want to use the upload functionality.
45+
`transformationPosition` is optional. The default value for this parameter is `TransformationPosition.PATH`. Acceptable values are `TransformationPosition.PATH` & `TransformationPosition.QUERY`
3746

3847
_Note: Do not include your Private Key in any client side code, including this SDK or its initialization._
3948

@@ -63,10 +72,8 @@ ImageKit.Companion.init(
6372
);
6473
```
6574

66-
## Sample application
67-
This project has a sample application under `sample` folder. The sample application demonstrates the use of this SDK.
75+
### Quick Examples
6876

69-
## Usage
7077
### URL construction
7178
#### Using image path
7279
```kotlin
@@ -151,57 +158,6 @@ ImageKit.Companion.getInstance()
151158
.create()
152159
```
153160

154-
### List of supported transformations
155-
The complete list of transformations supported and their usage in ImageKit can be found [here](https://docs.imagekit.io/imagekit-docs/image-transformations). The SDK provides a function for each transformation parameter, making the code simpler and readable. If a transformation is supported in ImageKit, but a name for it cannot be found in the table below, then use the `addCustomTransformation` function and pass the transformation code from ImageKit docs as the first parameter and value as second paramter. For example - `.addCustomTransformation("w", "400")`
156-
157-
| Supported Transformation Function | Translates to parameter |
158-
| ----------------------------- | ----------------------- |
159-
| height | h |
160-
| width | w |
161-
| aspectRatio | ar |
162-
| quality | q |
163-
| crop | c |
164-
| cropMode | cm |
165-
| focus | fo |
166-
| format | f |
167-
| radius | r |
168-
| background | bg |
169-
| border | bo |
170-
| rotation | rt |
171-
| blur | bl |
172-
| named | n |
173-
| overlayImage | oi |
174-
| overlayX | ox |
175-
| overlayY | oy |
176-
| overlayFocus | ofo |
177-
| overlayHeight | oh |
178-
| overlayWidth | ow |
179-
| overlayText | ot |
180-
| overlayTextFontSize | ots |
181-
| overlayTextFontFamily | otf |
182-
| overlayTextColor | otc |
183-
| overlayAlpha | oa |
184-
| overlayTextTypography | ott |
185-
| overlayBackground | obg |
186-
| progressive | pr |
187-
| lossless | lo |
188-
| trim | t |
189-
| metadata | md |
190-
| colorProfile | cp |
191-
| defaultImage | di |
192-
| dpr | dpr |
193-
| effectSharpen | e-sharpen |
194-
| effectUSM | e-usm |
195-
| effectContrast | e-contrast |
196-
| effectGray | e-grayscale |
197-
198-
### File Upload
199-
The SDK provides a simple interface using the `ImageKit.getInstance().uploader().upload` method to upload files to the ImageKit Media Library. It accepts all the parameters supported by the [ImageKit Upload API](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload#request-structure-multipart-form-data).
200-
201-
Make sure that you have specified `authenticationEndpoint` during SDK initialization. The SDK makes an HTTP GET request to this endpoint and expects a JSON response with three fields i.e. `signature`, `token` and `expire`.
202-
203-
[Learn how to implement authenticationEndpoint](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload#how-to-implement-authenticationendpoint-endpoint) on your server.
204-
205161
#### Upload file from bitmap
206162
``` kotlin
207163
// Kotlin
@@ -252,8 +208,6 @@ ImageKit.Companion.getInstance().uploader().upload(
252208
)
253209
```
254210

255-
256-
257211
#### Upload file using binary
258212
```kotlin
259213
// Kotlin
@@ -279,8 +233,204 @@ ImageKit.Companion.getInstance().uploader().upload(
279233
)
280234
```
281235

282-
## Support
236+
## Demo application
237+
* The official step by step iOS quick start guide - https://docs.imagekit.io/getting-started/quickstart-guides/ios
238+
* You can also run the demo application in [sample](/sample) folder.
239+
240+
## Components
241+
242+
The library includes 3 Primary Classes:
243+
244+
* [`ImageKit`](#ImageKit) for defining options like `urlEndpoint`, `publicKey` or `authenticationEndpoint` for the application to use.
245+
* `ImageKitURLConstructor` for [constructing image urls](#constructing-image-urls).
246+
* `ImageKitUploader`for client-side [file uploading](#file-upload).
247+
248+
## ImageKit
249+
In order to use the SDK, you need to provide it with a few configuration parameters.
250+
```kotlin
251+
// In kotlin
252+
import com.imagekit.android.ImageKit;
253+
254+
ImageKit.init(
255+
context = applicationContext,
256+
publicKey = "your_public_api_key",
257+
urlEndpoint = "https://ik.imagekit.io/your_imagekit_id",
258+
transformationPosition = TransformationPosition.PATH,
259+
authenticationEndpoint = "http://www.yourserver.com/auth"
260+
)
261+
```
262+
263+
```java
264+
// In Java
265+
import com.imagekit.android.ImageKit;
266+
267+
ImageKit.Companion.init(
268+
getApplicationContext(),
269+
"your_public_api_key",
270+
"https://ik.imagekit.io/your_imagekit_id",
271+
TransformationPosition.PATH,
272+
"http://www.yourserver.com/auth"
273+
);
274+
```
275+
* `urlEndpoint` is required to use the SDK. You can get URL-endpoint from your ImageKit dashboard - https://imagekit.io/dashboard#url-endpoints.
276+
* `publicKey` and `authenticationEndpoint` parameters are required if you want to use the SDK for client-side file upload. You can get these parameters from the developer section in your ImageKit dashboard - https://imagekit.io/dashboard#developers.
277+
* `transformationPosition` is optional. The default value for this parameter is `TransformationPosition.PATH`. Acceptable values are `TransformationPosition.PATH` & `TransformationPosition.QUERY`
278+
279+
> Note: Do not include your Private Key in any client-side code.
280+
281+
## Constructing Image URLs
282+
The `ImageKitURLConstructor` is used to create a url that can be used for rendering and manipulating images in real-time. `ImageKitURLConstructor` consists of functions that can be chained together to perform transformations.
283+
284+
`ImageKitURLConstructor` can be initialized by calling `ImageKit.getInstance().url(...)` with a set of parameters defined below.
285+
286+
| Parameter | Type | Description |
287+
| :----------------| :----|:----------------------------- |
288+
| urlEndpoint | String | Optional. The base URL to be appended before the path of the image. If not specified, the URL-endpoint specified in the parent `IKContext` component is used. For example, https://ik.imagekit.io/your_imagekit_id/endpoint/ |
289+
| path | String |Conditional. This is the path at which the image exists. For example, `/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. |
290+
| src | String |Conditional. This is the complete URL of an image already mapped to ImageKit. For example, `https://ik.imagekit.io/your_imagekit_id/endpoint/path/to/image.jpg`. Either the `path` or `src` parameter needs to be specified for URL generation. |
291+
| transformationPosition | [TransformationPosition](/imagekit/src/main/java/com/imagekit/android/ImagekitUrlConstructor.kt) |Optional. The default value is `.PATH` that places the transformation string as a URL path parameter. It can also be specified as `.QUERY`, which adds the transformation string as the URL's query parameter i.e.`tr`. If you use `src` parameter to create the URL, then the transformation string is always added as a query parameter. |
292+
293+
The transformations to be applied to the URL can be chained to `ImageKit.getInstance().url(...)`. See the list of [different tranformations](#list-of-supported-transformations). Different steps of a [chained transformation](https://docs.imagekit.io/features/image-transformations/chained-transformations) can be added by calling the function `chainTransformation`.
294+
295+
### Basic Examples
296+
```kotlin
297+
// Kotlin
298+
// https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-400.00,ar-3-2
299+
ImageKit.getInstance()
300+
.url(
301+
path = "default-image.jpg",
302+
transformationPosition = TransformationPosition.QUERY
303+
)
304+
.height(400f)
305+
.aspectRatio(3, 2)
306+
.create()
307+
```
283308

309+
```java
310+
// Java
311+
// https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-400.00,ar-3-2
312+
ImageKit.Companion.getInstance()
313+
.url(
314+
"default-image.jpg",
315+
TransformationPosition.QUERY
316+
)
317+
.height(400f)
318+
.aspectRatio(3, 2)
319+
.create()
320+
```
321+
322+
More Examples can be found in [URLGenerationTests.kt](imagekit/src/test/java/com/imagekit/android/URLGenerationTests.kt)
323+
324+
### List of supported transformations
325+
The complete list of transformations supported and their usage in ImageKit can be found [here](https://docs.imagekit.io/imagekit-docs/image-transformations). The SDK provides a function for each transformation parameter, making the code simpler and readable. If a transformation is supported in ImageKit, but if a name for it cannot be found in the table below, then use the `addCustomTransformation` function and pass the transformation code from ImageKit docs as the first parameter and value as the second parameter. For example - `.addCustomTransformation("w", "400")`
326+
327+
328+
<details>
329+
<summary>Expand</summary>
330+
331+
| Supported Transformation Name | Transformation Function Prototypes | Translates to parameter |
332+
| ----------------------------- | ---------------------------------- | ----------------------- |
333+
| height | height(height: Int) | h |
334+
| width | width(width: Int) | w |
335+
| aspectRatio | aspectRatio(width: Int, height: Int) | ar |
336+
| quality | quality(quality: Int) | q |
337+
| crop | crop(cropType: CropType) | c |
338+
| cropMode | cropMode(cropMode: CropMode) | cm |
339+
| x, y | focus(x: Int, y: Int) | x, y |
340+
| focus | focus(focusType: FocusType) | fo |
341+
| format | format(format: Format) | f |
342+
| radius | radius(radius: Int) | r |
343+
| background | background(backgroundColor: String) | bg |
344+
| border | border(borderWidth: Int, borderColor: String) | b |
345+
| rotation | rotation(rotation: Rotation) | rt |
346+
| blur | blur(blur: Int) | bl |
347+
| named | named(namedTransformation: String) | n |
348+
| overlayX | overlayX(overlayX: Int) | ox |
349+
| overlayY | overlayY(overlayY: Int) | oy |
350+
| overlayFocus | overlayFocus(overlayFocus: OverlayFocusType) | ofo |
351+
| overlayHeight | overlayHeight(overlayHeight: Int) | oh |
352+
| overlayWidth | overlayWidth(overlayWidth: Int) | ow |
353+
| overlayImage | overlayImage(overlayImage: String) | oi |
354+
| overlayImageTrim | overlayImageTrim(overlayImageTrim: Boolean) | oit |
355+
| overlayImageAspectRatio | overlayImageAspectRatio(width: Int, height: Int) | oiar |
356+
| overlayImageBackground | overlayImageBackground(overlayImageBackground: String) | oibg |
357+
| overlayImageBorder | overlayImageBorder(borderWidth: Int, borderColor: String) | oib |
358+
| overlayImageDPR | overlayImageDPR(dpr: Float) | oidpr |
359+
| overlayImageQuality | overlayImageQuality(quality: Int) | oiq |
360+
| overlayImageCropping | overlayImageCropping(cropMode: CropMode) | oic |
361+
| overlayText | overlayText(overlayText: String) | ot |
362+
| overlayTextFontSize | overlayTextFontSize(overlayTextFontSize: Int) | ots |
363+
| overlayTextFontFamily | overlayTextFontFamily(overlayTextFontFamily: OverlayTextFont) | otf |
364+
| overlayTextColor | overlayTextColor(overlayTextColor: String) | otc |
365+
| overlayTextTransparency | overlayTextTransparency(overlayTextTransparency: Int) | oa |
366+
| overlayAlpha | overlayAlpha(overlayAlpha: Int) | oa |
367+
| overlayTextTypography | overlayTextTypography(overlayTextTypography: OverlayTextTypography) | ott |
368+
| overlayBackground | overlayBackground(overlayBackground: String) | obg |
369+
| overlayTextEncoded | overlayTextEncoded(overlayTextEncoded: String) | ote |
370+
| overlayTextWidth | overlayTextWidth(width: Int) | otw |
371+
| overlayTextBackground | overlayTextBackground(overlayTextColor: String) | otbg |
372+
| overlayTextPadding | overlayTextPadding(overlayTextPadding: String)<br>overlayTextPadding(overlayTextPadding: Int)<br>overlayTextPadding(verticalPadding: Int, horizontalPadding: Int)<br>overlayTextPadding(topPadding: Int, horizontalPadding: Int, bottomPadding: Int)<br>overlayTextPadding(topPadding: Int, rightPadding: Int, bottomPadding: Int, leftPadding: Int) | otp |
373+
| overlayTextInnerAlignment | overlayTextInnerAlignment(overlayTextInnerAlignment: OverlayTextInnerAlignment) | otia |
374+
| overlayRadius | overlayRadius(radius: Int) | or |
375+
| progressive | progressive(flag: Boolean) | pr |
376+
| lossless | lossless(flag: Boolean) | lo |
377+
| trim | trim(flag: Boolean)<br>trim(value: Int) | t |
378+
| metadata | metadata(flag: Boolean) | md |
379+
| colorProfile | colorProfile(flag: Boolean) | cp |
380+
| defaultImage | defaultImage(defaultImage: String) | di |
381+
| dpr | dpr(dpr: Float) | dpr |
382+
| effectSharpen | effectSharpen(value: Int = 0) | e-sharpen |
383+
| effectUSM | effectUSM( radius: Float, sigma: Float, amount: Float, threshold: Float) | e-usm |
384+
| effectContrast | effectContrast(flag: Boolean) | e-contrast |
385+
| effectGray | effectGray(flag: Boolean) | e-grayscale |
386+
| original | original(flag: Boolean) | orig |
387+
388+
</details>
389+
390+
### File Upload
391+
The SDK provides a simple interface using the `ImageKit.getInstance().uploader().upload(...)` method to upload files to the ImageKit Media Library. It accepts all the parameters supported by the [ImageKit Upload API](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload#request-structure-multipart-form-data).
392+
393+
Make sure that you have specified `authenticationEndpoint` during SDK initialization. The SDK makes an HTTP GET request to this endpoint and expects a JSON response with three fields i.e. `signature`, `token`, and `expire`.
394+
395+
[Learn how to implement authenticationEndpoint](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload#how-to-implement-authenticationendpoint-endpoint) on your server.
396+
397+
The `ImageKit.getInstance().uploader().upload(...)` accepts the following parameters
398+
399+
| Parameter | Type | Description |
400+
| :----------------| :----|:----------------------------- |
401+
| file | Binary / Bitmap / String | Required.
402+
| fileName | String | Required. If not specified, the file system name is picked.
403+
| useUniqueFileName | Boolean | Optional. Accepts `true` of `false`. The default value is `true`. Specify whether to use a unique filename for this file or not. |
404+
| tags | Array of string | Optional. Set the tags while uploading the file e.g. ["tag1","tag2"] |
405+
| folder | String | Optional. The folder path (e.g. `/images/folder/`) in which the file has to be uploaded. If the folder doesn't exist before, a new folder is created.|
406+
| isPrivateFile | Boolean | Optional. Accepts `true` of `false`. The default value is `false`. Specify whether to mark the file as private or not. This is only relevant for image type files|
407+
| customCoordinates | String | Optional. Define an important area in the image. This is only relevant for image type files. To be passed as a string with the `x` and `y` coordinates of the top-left corner, and `width` and `height` of the area of interest in format `x,y,width,height`. For example - `10,10,100,100` |
408+
| responseFields | Array of string | Optional. Values of the fields that you want upload API to return in the response. For example, set the value of this field to `["tags", "customCoordinates", "isPrivateFile"]` to get value of `tags`, `customCoordinates`, and `isPrivateFile` in the response. |
409+
| imageKitCallback | [ImageKitCallback](imagekit/src/main/java/com/imagekit/android/ImageKitCallback.kt) | Required. |
410+
411+
Sample Usage
412+
```kotlin
413+
ImageKit.getInstance().uploader().upload(
414+
file = image,
415+
fileName = "sample-image.jpg",
416+
useUniqueFilename = true,
417+
tags = ["demo"],
418+
folder = "/",
419+
isPrivateFile = false,
420+
customCoordinates = "",
421+
responseFields = "",
422+
imageKitCallback = object: ImageKitCallback {
423+
override fun onSuccess(uploadResponse: UploadResponse) {
424+
// Handle Success Response
425+
}
426+
override fun onError(uploadError: UploadError) {
427+
// Handle Upload Error
428+
}
429+
}
430+
)
431+
```
432+
433+
## Support
284434
For any feedback or to report any issues or general implementation support please reach out to [[email protected]](mailto:[email protected])
285435

286436
## Links

0 commit comments

Comments
 (0)