Add Video Player (#32)

* Add an exception handling * Update README * Update README * Add PXLPhotoProductView with bookmark, need bookmark's click interface * Add a viewerActivity to demo * Add Kotlin for widgets * Add an interface for bookmark clicks * Add darkmode * Finalize DarkMode * Add a widget launcher in gallery * Add PXLPhotoView and its demo in PXLPhotoViewFragment * Change a param of ImageScaleType * Add a demo showing PXLPhotoView to RecyclerView * Add video view * Add videoPlayerManager * Fix video bugs Add interfaces for layout * Modulize a recyclerview for a list of PXLPhoto * Add theme * Improve product view * Remove unused codes * Move a util class to an util package * Move enum classes to enums package * Move data classes to data package * Move client related classes to client package * Add a new client for Kotlin.coroutines to use suspend in API requests * Add coroutines for album/pdp * Add coroutines to analytics * Remove unused codes * Add configuration classes for widgets * Fix a bug of using pdp * Reformat codes * Refactor a variable * Fix a bug in demo * Add load more for coroutines * Add albumId to demo * Update README * Update README * Update README * Update README * Update README * Update README * Update README.md * Update README * Update README * Update README * Update README * Update README * Add customizable product click listener Add PXLKtxAlbum to expose make the code readable for the SDK users * Update documentation * Update documentation * Split if else conditions into multiple lines * Update README * Update README * Add pxlKtxAlbum.getPhotoWithId() to demo Update README * Add kotlinx-coroutines-core to gradle Add kotlinx-coroutines-android to gradle Update README * Update README * Rename classes Update README * Update README * Fix a bug in analytics API * Add video player library codes temporary. this will be removed after optimizing its performance. * Remove a temporary code * Update document * Update README * Update README * Update README * Update doc * Update doc * Update doc * Update doc * Update doc * Update doc * Update doc * Update doc * Update document * Update document * Update document * Remove library codes and import a gradle dependency instead * Add a visibility to debug Text * Add a visibility to debug Text * Add a visibility to debug Text * Update document * Update document * Fix bugs in FIT_CENTER and CENTER_CROP for VideoPlayerView * Add comments Update README * Add comments Update README * Add comments * Add comments * Upgrade gradle libraries * Update README * Update README * Update README * Update README * Update README * Update README * Update doc * Upgrade Kotlin version * Rollback Kotlin version * Remove unused codes * Update doc * Import JZVideo library * Update document * Update document * Update document * Update document * Update document * Import JZVideo library * Add viewModelScope + try/catch * Replace the existing video library with a new one * Connect volume and looping to the new video player * Remove unused file * Improve the library * Upgrade JZVideo library
pixlee · Sep 28, 2020 · f87c9b8 · f87c9b8
1 parent 2db7051
commit f87c9b8
Show file tree

Hide file tree

Showing 160 changed files with 7,356 additions and 2,450 deletions.
diff --git a/.gitignore b/.gitignore
@@ -58,4 +58,8 @@ fastlane/report.xml
 fastlane/Preview.html
 fastlane/screenshots
 fastlane/test_output
-fastlane/readme.md  ₩
+fastlane/readme.md
+
+video-player-visibility-utils/
+video-player-manager/
+JZVideo/
diff --git a/README.md b/README.md
@@ -2,321 +2,67 @@
 This SDK makes it easy for Pixlee customers to find and download Pixlee images and albums.  There's a native wrapper to the Pixlee album API for Android, and there's also a demo app showing how easy it is to drop in and customize a UI. This repo includes both the Pixlee Android SDK and an example project to show you how it's used.  
 
 # Table of Content
-- [Get Started with Demo App](#Get-Started-with-Demo-App)
-- [Add the SDK to your App](#Add-the-SDK-to-your-App)
-- [Initialize SDK](#Initialize-SDK)
-    - [Register Pixlee credentials](#Register-Pixlee-credentials)
-    - [Get PXLClient](#Get-PXLClient)
-- [Album Features](#Album-Features)
-    - [Initiate Album or Product](#Initiate-Album-or-Product)
-    - [Get Photos of a Product](#Get-Photos-of-a-Product)
-    - [Get more Photos](#Get-more-Photos)
-    - [Uploading Photos](#Uploading-Photos)
-- [How to get image urls](#How-to-get-image-urls)
-- [Album Analytics](#Album-Analytics)
-    - [Opened Widget](#Opened-Widget)
-    - [Load More](#Load-More)
-    - [Opened Lightbox](#Opened-Lightbox)
-    - [Action Clicked](#Action-Clicked)
-- [Ecommerce Analytics](#Ecommerce-Analytics)
-    - [Add To Cart](#Add-To-Cart)
-    - [Conversion](#Conversion)
-- [UI components](#UI-components)
-    - [Image & Video Viewer with PXLPhoto](#Image-and-Video-Viewer-with-PXLPhoto)
-- Migration
-    - [from 1.0.6 or older](doc/migration/1.0.6.md)
-
-
+- [Get Started](#Get-Started)
+- [Run the Demo App](#Run-the-Demo-App)
+- [Development Guide](#Development-Guide)
+    - [Java](doc/JAVA.md)
+    - [Kotlin](doc/kotlin/INDEX.md)
+
+# Get Started
+- ### Add gradle dependencies
+    1. Add it in your root build.gradle at the end of repositories:
+        ```gradle
+        allprojects {
+            repositories {
+                ...
+                maven { url 'https://jitpack.io' }
+            }
+        }
+        ```
+    1. Add the dependency
+        - The latest $pixleeSDK is [![](https://jitpack.io/v/pixlee/android-sdk.svg)](https://jitpack.io/#pixlee/android-sdk)
+        - The latest $videoPlayerManager is [![](https://jitpack.io/v/pixlee/android-video-player.svg)](https://jitpack.io/#pixlee/android-video-player)
+        ```gradle
+        dependencies {
+                implementation 'com.github.pixlee:android-sdk:$pixleeSDK'
+
+                // (Optional) if you use UI components of the SDK, add this.
+                implementation "com.github.pixlee:android-video-player:$videoPlayerManager"
+
+                // (Optional) if you need to use PXLLoading, add this.
+                implementation "com.airbnb.android:lottie:3.4.1"
+        }
+        ```
 
-# Get Started with Demo App
+# Run the Demo App
 - The demo app included with this SDK are meant to be used in Android Studio to create a typical Android app.
-
-- To help you get up and running quickly, we've also built an sample application featuring a grid view, list view, and detail view.  The adapters simply maintain an ArrayList of PXLBaseAlbum, which is updated via calls to `loadNextPageOfPhotos`.  Since the data source contains the full PXLPhoto object, you can easily customize your own widgets to display the desired images and text.  The sample also implements a scroll listener which times calls to `loadNextPageOfPhotos` to provide the endless scroll effect. 
-An example of the proper usage of an opened lightbox event is also included in the sample app!
+- To help you get up and running quickly, we've built this demo featuring a RecyclerView with LinearLayoutManager and GridLayoutManager and a few UI components.
+- UI components demonstrated in the demo can be customize by adding arguments to the views simple.
+- API calls being fired via Kotlin.coroutines are in the demo. 
+- video: https://www.loom.com/share/37fb674d3cb348d48c3479b67a9bc2aa
 - <img src="doc/img/demo_1_main.jpg" width="24%"> <img src="doc/img/demo_2_album.jpg" width="24%"> <img src="doc/img/demo_2_album_filter.jpg" width="24%"> <img src="doc/img/demo_2_image_viewer.jpg" width="24%">
 - <img src="doc/img/demo_3_uploader.jpg" width="24%"> <img src="doc/img/demo_4_analytics.jpg" width="24%"> <img src="doc/img/demo_5_analytics.jpg" width="24%">
-
-1. Import this project into Android Studio
-2. Open .gitignore at the root of the project folder and Add 'pixleekey.properties' to the file 
-3. Generate **pixleekey.properties** at the root of the project folder
+1. Open .gitignore at the root of the project folder and Add 'pixleekey.properties' to the file
+1. Generate **pixleekey.properties** at the root of the project folder
     - <img src="doc/img/pixleekey.png" width="40%">
-4. Fill the file with the example below and edit it with your own credentials, albumId and SKU.  
+1. Fill the file with the example below and edit it with your own credentials, albumId and SKU.
 pixleeAPIKey and pixleeSecretKey are in here (https://app.pixlee.com/app#settings/pixlee_api)
 AlbumId and SKU available from the Pixlee dashboard).
-    ```
+    ```properties
     pixleeAPIKey=yours
     pixleeSecretKey=yours
     pixleeAlbumId=yours
     pixleeSKU=yours
     ```
     Example
-    ```
+    ```properties
     pixleeAPIKey=ccWQFNExi4gQjyNYpOEf
     pixleeSecretKey=b3b38f4322877060b2e4f390fd
     pixleeAlbumId=5984962
     pixleeSKU=35123
     ```
+1. Run the project on an Android device
 
-4. Run the project on an Android device
-
-# Add the SDK to your App
-- import pixleesdk as a library project into your project
-    1. Open your existing project in Android Studio
-    2. Go to Import Module (File -> New -> Import Module)
-    3. Enter the path of the pixlee-android-sdk directory
-    4. Select the modules you would like to import and click Finish.
-- [Google official doc: How to import a module](https://developer.android.com/studio/projects/add-app-module#ImportAModule)
-
-# Initialize SDK
-### You must do this before using this SDK!!
-#### Register Pixlee credentials
-- Before accessing any Pixlee API, you must initialize the `PXLClient`. To set the API key, call the static method initialize:
-    ```
-    // If you need only to use @Get APIs
-    #!java
-    
-    PXLClient.initialize(<PIXLEE API KEY>);
-    ```
-    Or:
-    ```
-    // If you need to use both @Get and @Post APIs
-    #!java
-    
-    PXLClient.initialize(<PIXLEE API KEY>, <PIXLEE SECRET KEY>);
-    ```
-#### Get PXLClient
-- You can then use the singleton instance to make calls against the Pixlee API:
-    ```
-    #!java
-    
-    PXLClient client = PXLClient.getInstance(context);
-    ```
-## Album Features
-### Initiate Album or Product
-- #### Option 1: Album    
-    To load the photos in an album, you'll want to use the `PXLAlbum` class. Instantiate one with your album ID and client:
-        
-    ```
-    #!java
-    
-    PXLBaseAlbum album = new PXLAlbum(<ALBUM ID>, client);
-    ```
-    Or:
-    ```
-    #!java
-    
-    PXLBaseAlbum album = new PXLAlbum(<ALBUM ID>, client.getBasicRepo(), client.getAnalyticsRepo());
-    ```
-- #### Option 2: Product    
-    To load the photos in an Product album, you'll want to use the `PXLPdpAlbum` class. Instantiate one with your desired sku and client:
-        
-    ```
-    #!java
-    
-    PXLBaseAlbum album = new PXLPdpAlbum(<SKU>, client);
-    ```
-    Or:
-    ```
-    #!java
-    
-    PXLBaseAlbum album = new PXLPdpAlbum(<SKU>, client.getBasicRepo(), client.getAnalyticsRepo());
-    ```
-#### Get more Photos
-- You can then set sort and filter options if desired and use `loadNextPageOfPhotos` to kick off the async request.   
-    ```
-    #!java
-    
-    PXLAlbumFilterOptions filterOptions = new PXLAlbumFilterOptions();
-    filterOptions.minTwitterFollowers = 1000;
-    filterOptions.minInstagramFollowers = 2000;
-    PXLAlbumSortOptions sortOptions = new PXLAlbumSortOptions();
-    sortOptions.sortType = PXLAlbumSortType.DYNAMIC;
-    sortOptions.descending = true;
-    album.setPerPage(15);
-    album.setFilterOptions(filterOptions);
-    album.setSortOptions(sortOptions);
-    album.loadNextPageOfPhotos(this);
-    ```
-- Each successive call of `loadNextPageOfPhotos` will load the next page of photos. Be sure to set all of your request options (filters, sort, etc) before calling `loadNextPageOfPhotos`.  See the source for more implementation details.
-  Once an album has loaded photos from the server, it will instantiate `PXLBaseAlbum` objects that can be consumed by your UI. `PXLBaseAlbum` exposes all of the data for a photo available through the Pixlee API and offers several image url sizes depending on your needs.
-    
-#### Uploading Photos
-- Prerequisite:
-    - [Initiate Album or Product](#Initiate-Album-or-Product)
-    - prepare PXLBaseAlbum and declare a variable as 'album' 
-- Option 1: Upload an image url
-    
-    ```
-    #!java
-    album.uploadImage(
-                "<title>",
-                "<email>",
-                "<name>",
-                "<image URL>",
-                <true/false>,
-                new PXLBaseAlbum.RequestHandlers<MediaResult>() {
-                    @Override
-                    public void onComplete(MediaResult result) {
-                        // process the result 
-                    }
-
-                    @Override
-                    public void onError(String error) {
-                        // error
-                    }
-                });
-    ```
-- Option 2: Upload an image file
-    ```
-    album.uploadLocalImage(
-                "<title>",
-                "<email>",
-                "<name>",
-                <true/false>,
-                "<local image path>",
-                new PXLBaseAlbum.RequestHandlers<MediaResult>() {
-                    @Override
-                    public void onComplete(MediaResult result) {
-                        // process the result
-                    }
-
-                    @Override
-                    public void onError(String error) {
-                        // error
-                    }
-                });
-    ```    
-
-## How to get image urls
-Some imageURL fields can be empty or null depending on its data's status. In order to get appropriate images, you can use this method.
-```
-#!java
-photo.getUrlForSize(PXLPhotoSize.ORIGINAL)
-photo.getUrlForSize(PXLPhotoSize.BIG)
-photo.getUrlForSize(PXLPhotoSize.MEDIUM)
-photo.getUrlForSize(PXLPhotoSize.THUMBNAIL)
-```
-    
-## Album Analytics
-
-
-#### Opened Widget & Widget Visible
-Be aware of the difference between **Opened Widget** and **Widget Visible**. (Need a sample code. Check the demo app in the project)
-
-There is an order of firing these two APIs.
-1. **Opened Widget**: You should fire this when firing the api is done and loading the photo data into your own view for the widget is complete.
-2. **Widget Visible**: **Opened Widget** should be fired first. Then, you can fire this when your own view for the widget started to be visible on the screen.
-
-- ##### Opened Widget
-    - To fire this event, simply call the `openedWidget` method of the PXLAlbum or PXLPdpAlbum AFTER data has been returned from the first call of the `loadNextPageOfPhotos` method, and an "Opened Widget" event will be fired containing all of the necessary analytics information.
-    See the onComplete function in GalleryFragment.java for an example.
-    
-        ```
-        #!java
-        
-        album.openedWidget(PXLWidgetType.photowall);
-        album.openedWidget(PXLWidgetType.horizontal);
-        album.openedWidget("<Customized name>"); 
-        ```
-    
-- #### Widget Visible
-    - To fire this event, simply call the `widgetVisible` method of the PXLAlbum or PXLPdpAlbum AFTER data has been returned from the first call of the `loadNextPageOfPhotos` method, and an "Widget Visible" event will be fired containing all of the necessary analytics information.
-
-        ```
-        #!java
-        
-        album.widgetVisible(PXLWidgetType.photowall);
-        album.widgetVisible(PXLWidgetType.horizontal);
-        album.widgetVisible("<Customized name>"); 
-        ```
-
-#### Load More
-- To fire a load more event, simply call the `loadMore` method of the PXLAlbum or PXLPdpAlbum AFTER data has been returned from calls via the 'loadNextPageOfPhotos' method, a "Load More" analytics event will be fired containing all of the necessary analytics information.
-See the onComplete function in GalleryFragment.java for an example.
-- On calls to loadNextPageOfPhotos (except the first), a "Load More" analytics event will be fired automatically
-    ```
-    #!java
-    
-    album.loadMore();
-    ```
-
-#### Opened Lightbox
-- To fire an opened ligtbox event, simply call the `openedLightbox` method of the PXLBaseAlbum that is being opened, and an "Opened Lightbox" event will be fired containing all of the necessary analytics information.
-
-    ```
-    #!java
-    
-    album.openedLightbox(photo.albumPhotoId)
-    album.openedLightbox(photo)
-    ```
-
-#### Action Clicked
-- To fire an action clicked event, simply call the `actionClicked` method of the PXLBaseAlbum that the action click is being driven from and pass in the URL of the link that the user is being redirected to.  An "Action Clicked" event will be fired containing all of the necessary analytics information.
-
-    ```
-    #!java
-    
-    album.actionClicked(photo.albumPhotoId, "https://ca.puma.com/en/ca/pd/clyde-court-core-basketball-shoes/191712.html");
-    album.actionClicked(photo, "https://ca.puma.com/en/ca/pd/clyde-court-core-basketball-shoes/191712.html");
-
-    ```
-## Ecommerce Analytics
-- initialize:
-    ```
-    #!java
-    
-    PXLAnalytics analytics = new PXLAnalytics(client);
-    ```
-    Or:
-    ```
-    #!java
-    
-    PXLAnalytics analytics = new PXLAnalytics(client.getAnalyticsRepo());
-    ```
-    
-#### Add To Cart
-- To fire an Add To Cart event, simply call the `addToCart` method of the PXLAnalytics object with the necessary parameters, and an "Add To Cart" event will be fired containing all of the necessary analytics information.
-The parameters for this method are:
-    - [Required] sku  (String)
-    - [Required] price (String)
-    - [Required] quantity (Integer)
-    - [Optional] currency (String)
-
-    ```
-    #!java
-    analytics.addToCart("sku123", "123", 4);
-    ```
-
-#### Conversion
-- To fire a Conversion event, simply call the `conversion` method of the PXLAnalytics object with the necessary parameters, and a "Conversion" event will be fired containing all of the necessary analytics information.
-The parameters for this method are:
-    - [Required] cartContents  (ArrayList<HashMap<String, Object>>)
-    - [Required] cartTotal (String)
-    - [Required] cartTotalQuantity (Integer)
-    - [Optional] orderId (String)
-    - [Optional] currency (String)
-    
-    ```
-    #!java
-    
-    ArrayList<HashMap<String, Object>> cartContents = new ArrayList();
-    HashMap<String, Object> cart1 = new HashMap();
-    cart1.put("price", "123");
-    cart1.put("product_sku", "test123");
-    cart1.put("quantity", "4");
-    
-    cartContents.add(cart1);
-    analytics.conversion(cartContents, "123", 4);
-    ```
-
-## UI components
-#### Image and Video Viewer with PXLPhoto
-- after receiving PXLPhoto list via PXLBaseAlbum.loadNextPageOfPhotos(...), you can launch watch the content using PXLPhotoViewerActivity. Depending on its content_type, PXLPhotoViewerActivity will play a video or display a photo.
-- you can use the activity using the code here
-    ```
-    PXLPhotoViewerActivity.launch(getContext(), pxlPhoto, "photo name");
-    PXLPhotoViewerActivity.launch(getContext(), pxlPhoto);
-    ```
-
-# License
-pixlee-android-sdk is available under the MIT license.
+# Development Guide
+### [Java](doc/JAVA.md)
+### [Kotlin](doc/kotlin/INDEX.md)