programming guide - pen - developer.samsung.com · android version android ice cream sandwich 4.0...

Copyright © Samsung Electronics, Co., Ltd. All rights reserved.

Programming Guide: PEN.UP SDK for Android

penup-sdk-1.0.0

15 May 2015

PEN.UP Programming Guide

Copyright © Samsung Electronics, Co., Ltd. All rights reserved. Page | 2

1. OVERVIEW .........................................................................................................................................................3 1.1. PEN.UP SDK ............................................................................................................................................................. 3 1.2. ARCHITECTURE ........................................................................................................................................................ 4

2. DEVELOPMENT ENVIRONMENT...........................................................................................................................9 2.1. PREREQUISITES ....................................................................................................................................................... 9 2.2. PEN.UP SDK ............................................................................................................................................................. 9 2.3. APPLICATION REGISTRATION .................................................................................................................................. 9

3. PEN.UP SDK FUNDAMENTALS ........................................................................................................................... 11 3.1. IMPORTING THE PEN.UP LIBRARY PROJECT ......................................................................................................... 11 3.2. PERMISSION .......................................................................................................................................................... 11

4. PEN.UP SDK FEATURES ..................................................................................................................................... 12 4.1. CONNECTION ........................................................................................................................................................ 12 4.2. POSTING ARTWORKS ............................................................................................................................................ 12 4.3. ADDING COLLECTIONS .......................................................................................................................................... 14 4.4. RETRIEVING PEN.UP RESOURCES .......................................................................................................................... 14

5. USE CASES ........................................................................................................................................................ 16 5.1. CONNECTING TO THE PEN.UP SERVICE ................................................................................................................ 16 5.2. POSTING AN ARTWORK ........................................................................................................................................ 17 5.3. GETTING MY PROFILE ............................................................................................................................................ 18 5.4. GETTING MY FEED ................................................................................................................................................. 18 5.5. GETTING POPULAR ARTWORKS POSTED VIA YOUR APPLICATION ....................................................................... 19

6. SAMPLE APPLICATION ...................................................................................................................................... 20 6.1. SIMPLEPENUP ....................................................................................................................................................... 20

COPYRIGHT .............................................................................................................................................................. 22

Table of Contents



1. Overview PEN.UP is a creative social network service dedicated to digital arts. Users can share their own artworks as artists, follow other artists, comment on their artworks, and collect favorite artworks.

The PEN.UP environment is attractive, which expands the user experience from their own resources up to the PEN.UP community’s resources. The Android SDK for PEN.UP is released to help developers create applications that benefit from the PEN.UP services. It enables your application to post artworks and access the PEN.UP resources. Artworks posted via applications that use the PEN.UP SDK have deep linking information to link to the application page in Google Play to show an application overview and download it. The number of the application downloads will increase if artworks posted via your application are brilliant and they draw people toward your application with deep linking.

A glossary for the PEN.UP SDK for Android is listed up in the following table.

Term Description

PEN.UP application An Android application for the PEN.UP service

PEN.UP library A library in the PEN.UP SDK. It provides APIs for using PEN.UP functionalities.

PEN.UP server A server that handles authorization and requests for the PEN.UP service

PEN.UP service A social network service based on digital arts of user own

Table 1: Glossary

1.1. PEN.UP SDK

The PEN.UP SDK enables the following features:

- Authentication

Connecting to the PEN.UP service based on OAuth 2.0

Supporting Single Sign-On (SSO) with the PEN.UP application whose version is 1.5.0 or above

- Post PEN.UP resources

Posting a new artwork or adding a new collection

Post Dialog which provides a simple interface to post an artwork easily

Deep linking to your application when posting an artwork

- Access to PEN.UP resources

Getting information such as artists, artworks, collections, and tags

The SDK contains the PEN.UP library and it enables your application to get an approval for the connection through the PEN.UP authorization server and access the PEN.UP resources.



Figure 1: PEN.UP SDK overview

PEN.UP provides the following resources:

Artwork

It is a digital content drawn by users. It can be posted to the PEN.UP server and includes the artist name who posted the artwork, title, description, favorite count of other users, and so on. In the PEN.UP application, a posted artwork can be reposted by another user but its original artist and artwork record are retained.

Artist

It indicates information for a person who posts the artworks and contains metadata for the name, description, profile image URL and posted count. The artist profile is created when the user joins to the PEN.UP service. Users can get their own profile, their followers, or the specific artist information through the artist resource.

Collection

Users can make their own collections and add their own artworks or interesting artworks to the specific collection.

Tag

Artworks can be retrieved with the specific tag which is added to posted artworks.

1.2. Architecture

The PEN.UP service is composed of your application and its server. The detailed description is stated below.

Your Application

Your application contains the PEN.UP library and sends requests to the PEN.UP server to access PEN.UP resources after getting authorization.



PEN.UP Server

The PEN.UP server is composed of the authorization and resource server [Figure 2: PEN.UP architecture - system context view]. A user needs to have one of the following accounts: Samsung, Facebook, Google+, or Twitter. The authorization server identifies your application through account servers when your application connects to the PEN.UP server. After the client gets authorization, the resource server handles the requests of your application and sends the request result for artists, artworks, collections, and tags back.

Figure 2: PEN.UP architecture - system context view

The PEN.UP library provides the PenupClient and Api classes to enable a connection with the PEN.UP server and send requests for PEN.UP resources. The following figure describes the conceptual model view.



Figure 3: PEN.UP architecture - conceptual model view

The PEN.UP library provides two packages:

- com.samsung.android.penup

- com.samsung.android.penup.model

Figure 4: Package diagram of PEN.UP

Each package of the PEN.UP library has its classes and interfaces, and its relationships are drawn in Figures 5 and 6.

In the class diagram of the com.samsung.android.penup package, a PenupClient instance is returned through build() of the PenupClient.Builder class. Artist, artwork, collection, and tag resources are requested with the PenupClient instance. The response of each request is retrieved with Callback interfaces.



Figure 5: Class diagram of com.samsung.android.penup

The com.samsung.android.penup.model package handles PEN.UP resources including the artist, artwork, collection and tag information which implements the Resource class.

Figure 6: Class diagram of com.samsung.android.penup.model

Interfaces and classes of the PEN.UP library are described in the following table. Detailed information for each class and interface is in the API Reference provided under the [sdk-home]\Docs\api-reference folder.

com.samsung.android.penup Package

Interface / Class Description

PenupClient This class authenticates a user and manages the session for PEN.UP.

PenupClient.Builder This class configures and builds a PenupClient instance.



PenupClient.ConnectionCallback This interface receives a response for the connection request as an asynchronous callback.

ArtistApi This class sends requests related to ArtistResource.

ArtworkApi This class sends requests related to ArtworkResource.

CollectionApi This class sends requests related to CollectionResource.

TagApi This class sends requests related to TagResource.

ResponseResult This class represents the result of the response received from the PEN.UP service.

ResourceCallback<E extends Resource> This interface receives a response and a resource as an asynchronous callback.

ResourceListCallback<E extends Resource> This interface receives a response and a resource list as an asynchronous callback.

com.samsung.android.penup.model Package

Interface / Class Description

Resource This interface defines the resource of PEN.UP.

ArtistResource This class contains meta data of the artist such as a name, a description.

ArtworkResource This class contains meta data of the artwork such as a title, a description.

CollectionResource This class contains meta data of the collection such as a name, a follower count.

TagResource This class contains meta data of the tag such as a name, the follower count.

Table 2: Interfaces and classes of PEN.UP



2. Development Environment To develop applications with the PEN.UP feature, check the prerequisites for the SDK first and download the SDK.

2.1. Prerequisites

Before downloading the PEN.UP SDK and starting developing an application, refer to the following information.

Android Version

Android Ice Cream Sandwich 4.0 (API 14) or above

Available Devices

Android Ice Cream Sandwich devices or above

2.2. PEN.UP SDK

The PEN.UP SDK contains the following content for the application development.

Folder in SDK Description

doc API Reference

PEN.UP API descriptions based on Javadoc

Programming guide

Contains development information to use PEN.UP functionalities.

lib penup-v1.0.0

PEN.UP library project to use PEN.UP APIs

sample SimplePenup

A simple sample application to show PEN.UP API usage

Table 3: PEN.UP SDK content

2.3. Application Registration

Your application needs the client ID. It is used to connect to the PEN.UP service and is able to access PEN.UP resources. To get the client ID, the following information is required.

Application name

The application name to be displayed

Package name

Make the application package name for deep linking as below. The corresponding application should be registered in Google Play.

E.g. com.companyname.applicationname



Application icon

Set the icon as the 512 x 512 size, 32-bit png with alpha channel.

Key hash

Run the keytool utility in the terminal. The key hash in each environment can be retrieved as below. For more information, you may inquire by sending an email to [email protected].

1. For the debug

[Linux]

keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64

[Window]

keytool -exportcert -alias androiddebugkey -keystore %HOMEPATH%\.android\debug.keystore | openssl sha1 -binary | openssl base64

Enter "android" for the keystore password if using debug.keystore.

2. For the release

[Window]

keytool -exportcert -alias <RELEASE_KEY_ALIAS> -keystore <RELEASE_KEY_PATH> | openssl sha1 -binary | openssl base64

Make sure of the password that you set when you created the release key.

The information above is used to register your application to the App Registration page of the PEN.UP SDK in the Samsung Developer Site. Soon after your application is registered, an email containing the client IDs for debug and release will be sent to you.

The client ID for debug enables the sharing of artworks posted with your application only between you and the other users that are following you. The client ID for release makes your artworks shareable to all users. Therefore, use the client ID for testing and debugging your application and be careful not to upload unintended artworks.



3. PEN.UP SDK Fundamentals If you check the prerequisites for the application development and get the SDK content, you are now ready to start creating an application. The following sections let you know the fundamentals on using the PEN.UP APIs in your application.

Caution

1. Applications may post drawings using PEN.UP SDK, but shall not post photos or files of other formats. 2. Applications shall obtain prior written consent of the signed-in users before using signed-in users' artworks

for commercial purpose.

3. Applications shall not use artworks for commercial purposes, unless applications obtain prior written consent for use from the rightful owner of such artworks.

3.1. Importing the PEN.UP Library Project

The following steps describe how to import the PEN.UP library project.

1. Launch Eclipse.

2. Select File > Import > Android > Existing Android Code Into Workspace and click Next.

3. Select Browse… and enter <penup-sdk-folder>/Libs/.

4. Select penup-v1.0.0. Click Finish to import.

After importing the project, properties of your application project should be updated.

1. Click Project > Properties.

2. Select Android in the left navigation.

3. Click Add… and select penup-v1.0.0 to add the PEN.UP library project dependency.

3.2. Permission

In order to connect to the PEN.UP server, the following permissions are required. Add them to the AndroidManifest.xml file.

<uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>



4. PEN.UP SDK Features Detailed descriptions for PEN.UP are written below.

4.1. Connection

The first step when using the PEN.UP service is connecting to the PEN.UP server. Getting authorization from PEN.UP server enables access to the PEN.UP resources. PEN.UP authorization follows OAuth 2.0 (RFC 6749) and it needs the client ID and scope definition for accessing PEN.UP resources.

OAuth 2.0 scopes are as follows:

- POST_RESOURCES

- READ_MY_RESOURCES

- READ_RESOURCES

Each scope represents the access region for posting or reading resources. Add required access scope for the application.

The connection result can be checked whether the connection is successfully completed or failed by using the connection callback interface. Your application needs to connect to the PEN.UP service after checking if the service is connected whenever the application is launched.

Single Sign-On (SSO) is also supported. If the PEN.UP application 1.5.0 or above is installed, Single Sign-On is automatically enabled. If the user is already logged in, your application using the PEN.UP SDK can be connected with the same account.

4.2. Posting Artworks

A picture drawn by the user can be posted to the PEN.UP server and it is posted with the following information:

- Artwork title

- Artwork description

- Collection ID where the artwork is included

The allowed file formats of artworks are jpg and png. The PEN.UP library provides two methods to post an artwork, postArtwork() and launchPostDialog(), in the ArtworkApi class. If the application has its own UI concept and implements the posting menu by itself, the former is proper. The latter contains a simple UI dialog and it is useful if additional UI consideration is not required. The following figure shows a screen shot of a dialog for posting an artwork. A user can enter the title and description, and select the collection item.



Figure 7: A dialog for posting an artwork

The posted artwork by your application is identified with the client ID and provides deep linking information. A common use case of deep linking is below.

1. An artwork is posted by your application.

2. The artwork posted by your application is shown on PEN.UP application.

3. An icon of your application is shown in detailed information of the artwork.

4. A user selects the icon.

5-1. If the application is installed, the application that posts the artwork is launched.

5-2. If the application is not installed, the Google Play page is opened to install the application.

The following figure describes the use case.



Figure 8: Deep linking

4.3. Adding Collections

The user can add collections and set the specific artwork’s collection when it is posted.

4.4. Retrieving PEN.UP Resources

Following PEN.UP resources can be retrieved from the PEN.UP server though the PEN.UP library.



Artwork

- User’s artworks

- All artworks on the PEN.UP server

- Artworks for a user’s feed (The user’s feed for the specific artworks can be defined in PEN.UP.)

- The specific artwork

- Artworks for the specific artist

- Artworks for the specific collection

- Artworks for the specific tag

- Artworks posted via your application

- Popular artworks during a week, a month, or a whole period

- Popular artworks with specific tag during a week, a month, or a whole period

- Popular artworks posted via your application during a week, a month, or a whole period

Artist

- User’s profile

- The specific artist

- Artists whom the user follows (The user can set interesting artists to follow in PEN.UP.)

- Artists which follow the user

- Popular artists

Collection

- User’s collections

- The specific collection

- Collections of following artists which the user follow

Tag

- All tags on the PEN.UP server

- Tags of other artists which the user follows

- The specific tag



5. Use Cases - Connecting to the PEN.UP service

- Posting an artwork

- Getting my profile

- Getting my feed

- Getting popular artworks posted via your application

5.1. Connecting to the PEN.UP Service

In order to connect to PEN.UP service, your application should check and initialize the PenupClient and call connect(). The PenupClient should be configured as:

- Client ID

The OAuth 2.0 client ID issued from PEN.UP

- Scopes

The OAuth 2.0 scopes requested by your application

- Callback

The connection callback to receive the connection result

Once connected, the connection can be kept for 30 days. It is better to check the connection using isConnected() before calling connect().

The example code is written below:

// Configure the PenupClient PenupClient.Builder builder = new PenupClient.Builder(this); builder.setClientId(CLIENT_ID); builder.setCallback(new ConnectionCallback() { @Override public void onConnectionFailed(ResponseResult responseResult) { // Check the response result for connection and try to connect again } @Override public void onConnected() { // Call APIs for required PEN.UP resources } }); builder.addScope(Scope.READ_MY_RESOURCES) builder.addScope(Scope.READ_RESOURCES) builder.addScope(Scope.POST_RESOURCES) // Create an instance of PenupClient



PenupClient penupClient = builder.build(); if (!isConnected()) { // If not connected, connect to PEN.UP service penupClient.connect();

}

5.2. Posting an Artwork

First, the information such as a title and a description should be set to an ArtworkResource instance.

ArtworkResource artwork = new ArtworkResource(); artwork.setTitle("sample_image_title"); artwork.setDescription("sample_image_description"); artwork.setCollectionId(collectionId);

To post an artwork, call postArtwork() of ArtworkApi. After posting an artwork, the information about the posted artwork is received.

String imagePath = “IMAGE_PATH”;

ArtworkApi.postArtwork(penupClient, artwork, Uri.parse(imagePath), new ResourceCallback<ArtworkResource>() { @Override public void onCompleted(ResponseResult responseResult, ArtworkResource resource { if (responseResult.isSuccess() == true) { // Get the property of the artwork } else if (responseResult == CODE_AUTHENTICATION_REQUIRED || responseResult == CODE_ACCESS_TOKEN_EXPIRED || responseResult == CODE_INVALID_ACCESS_TOKEN) { // Try to connect to PEN.UP again. // After the connection is established, call postArtwork() again. } else { // Error handling } } });

Also, you can just use launchPostDialog() of ArtworkApi to post an artwork. After posting an artwork, the information about the posted artwork is received.

ArtworkApi.launchPostDialog(penupClient, Uri.parse(imagePath), new ResourceCallback<ArtworkResource>() { @Override public void onCompleted(ResponseResult responseResult, ArtworkResource resource { if (responseResult.isSuccess() == true) { // Get the property of the artwork } else if (responseResult == CODE_AUTHENTICATION_REQUIRED || responseResult == CODE_ACCESS_TOKEN_EXPIRED || responseResult == CODE_INVALID_ACCESS_TOKEN) { // Try to connect to PEN.UP again. // After the connection is established, call launchPostDialog() again. } else {



// Error handling } } });

5.3. Getting My Profile

To get the current user’s profile, call getMyProfile() of ArtistApi. Itsresponse contains an ArtistResource instance related to the signed-in user’s profile.

ArtistApi.getMyProfile(penupClient, new ResourceCallback<ArtistResource>() { @Override public void onCompleted(ResponseResult responseResult, ArtistResource resource) { if (responseResult.isSuccess() == true) { // Get the property of the artist } else if (responseResult == CODE_AUTHENTICATION_REQUIRED || responseResult == CODE_ACCESS_TOKEN_EXPIRED || responseResult == CODE_INVALID_ACCESS_TOKEN) { // Try to connect to PEN.UP again. // After the connection is established, call getMyProfile() again. } else { // Error handling } } });

5.4. Getting My Feed

To get the current user’s feed, call getMyFeed() of ArtworkApi. Its response contains a limit number of artworks set by maxResults and the next page token for the next request.

class MyFeedList implements ResourceListCallback<ArtworkResource> { void getMyFeed() {

// Send the request for getting the first page of the signed-in user’s feed

ArtworkApi.getMyFeed(MainActivity.sPenupClient, 15, null, this); } public void onCompleted(ResponseResult responseResult, List<ArtworkResource> resourceList, String nextPageToken) { if (responseResult.isSuccess() == true) { // Get the property of each artwork for (ArtworkResource artwork : resourceList) { }

// Send the request for getting the next page of the signed-in user’s feed

if (nextPageToken != null) {



ArtworkApi.getMyFeed(MainActivity.sPenupClient, 15, nextPageToken, this); } } else if (responseResult == CODE_AUTHENTICATION_REQUIRED || responseResult == CODE_ACCESS_TOKEN_EXPIRED || responseResult == CODE_INVALID_ACCESS_TOKEN) { // Try to connect to PEN.UP again. // After the connection is established, call getMyFeed() again. } else { // Error handling } } }

5.5. Getting Popular Artworks Posted via Your Application

You can get popular artworks not only in the PEN.UP service entirely but also from those posted via your application. To get the popular artworks posted via your application, call getPopularArtworksByApp() of ArtworkApi. Its response contains a limit number of artworks set by maxResults and the next page token for the next request.

class PopularArtworkList implements ResourceListCallback<ArtworkResource> { void getPopularArtworksByApp() { // Send the request for getting the popular artworks posted via your application ArtworkApi.getPopularArtworksByApp(MainActivity.sPenupClient, Period.WEEK, 15, null, this); } public void onCompleted(ResponseResult responseResult, List<ArtworkResource> resourceList, String nextPageToken) { if (responseResult.isSuccess() == true) { // Get the property of each artwork for (ArtworkResource artwork : resourceList) { }

// Send the request for getting the next page of the signed-in user’s feed

if (nextPageToken != null) { ArtworkApi.getPopularArtworksByApp(MainActivity.sPenupClient, Period.WEEK, 15, nextPageToken, this); } } else if (responseResult == CODE_AUTHENTICATION_REQUIRED || responseResult == CODE_ACCESS_TOKEN_EXPIRED || responseResult == CODE_INVALID_ACCESS_TOKEN) { // Try to connect to PEN.UP again. // After the connection is established, call getPopularArtworksByApp() again. } else { // Error handling } } }



6. Sample Application The PEN.UP SDK provides SimplePenup as a sample application.

6.1. SimplePenup

The SimplePenup shows how to use APIs of the PEN.UP SDK.

Figure 3: SimplePenup

The SimplePenup provides the following functions:

- Connects and disconnects to the PEN.UP service

- Posts an artwork

- Posts an artwork with the dialog for posting

- Add a collection

- Get the following resources

Current user’s profile

Current user’s artworks

Current user’s posts

Current user’s reposts



Current user’s feeds

Current user’s followings

Current user’s followers

Current user’s collections

Specific profile of another user

Specific artworks of another user

All artworks

All tags

Artworks posted via SimplePenup

Popular artists

Popular artworks

Popular artworks posted via SimplePenup



Copyright

Copyright © 2015 Samsung Electronics Co. Ltd. All Rights Reserved.

Though every care has been taken to ensure the accuracy of this document, Samsung Electronics Co., Ltd. cannot accept responsibility for any errors or omissions or for any loss occurred to any person, whether legal or natural, from acting, or refraining from action, as a result of the information contained herein. Information in this document is subject to change at any time without obligation to notify any person of such changes.

Samsung Electronics Co. Ltd. may have patents or patent pending applications, trademarks copyrights or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give the recipient or reader any license to these patents, trademarks copyrights or other intellectual property rights.

No part of this document may be communicated, distributed, reproduced or transmitted in any form or by any means, electronic or mechanical or otherwise, for any purpose, without the prior written permission of Samsung Electronics Co. Ltd.

The document is subject to revision without further notice.

All brand names and product names mentioned in this document are trademarks or registered trademarks of their respective owners.

For more information, please visit http://developer.samsung.com/

http://developer.samsung.com/

programming guide - pen - developer.samsung.com · android version android ice cream sandwich 4.0...

Documents