GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android...

20
GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide April 13, 2012 GREE, Inc. Copyright © 2012 GREE, Inc. All Rights Reserved.1

Transcript of GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android...

Page 1: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

GREE Platform Android SDK Ver. 3.0.0 αDeveloper's Guide

April 13, 2012GREE, Inc.

Copyright © 2012 GREE, Inc. All Rights Reserved.1

Page 2: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

Version HistoryDate Updates Changed Version

2/22/2012 First edition - 1.04/13/2012 Alpha 2 release Information

and formatting clean up

1.1

Copyright © 2012 GREE, Inc. All Rights Reserved.2

Page 3: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

Copyright © 2012 GREE, Inc. All Rights Reserved.3

Page 4: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

Table of Contents 1. GREE Platform Android SDK Outline

1.1 Requirements1.2 Distribution1.3 Required Knowledge1.4 Guideline Compliance

2. Before Beginning Development

2.1. Setting Up the GREE Sandbox

3. Setting Up the Development Environment

3.1. Importing the Library3.1.1. Downloading the SDK3.1.2. Adding Project and SDK to Eclipse3.1.3. Creating Application Project3.1.4. Referencing the GREE SDK from the Project

3.2. Gadget XML

4. Building a Sample App

4.1. Setting up Initialization File4.2. Handling Initialization4.3. Setting Up AndroidManifest.xml

5. Testing Created Apps

5.1. Building a Developed App.5.2. Running the App on the Simulator

6. Calling Login/Logout Functions

6.1. Login Processing6.2. Logout Processing6.3. Execution

Appendix: Error Message List

A1. OAuthA2. Initialization / Misc.

Copyright © 2012 GREE, Inc. All Rights Reserved.4

Page 5: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

1. GREE Platform Android SDK Outline

The GREE Platform Android SDK(SDK) allows programmers to implement

the functions provided by the GREE social network within Android-compatible applications (apps).

Please consult the GREE Platform Overview document included within the

package for information on the functions this SDK offers.

Copyright © 2012 GREE, Inc. All Rights Reserved.5

Page 6: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

1.1. Requirements Compatible devices

OS Compatible withAndroid 2.2 and higher

(*)API Level 8 and higher(*)Tablets not supported

GREE Platform Android SDK version

SDK VersionGREE Platform Android SDK

3.0.0 α Development environment

開発環境 VersionJDK Java SE Development Kit 6 Update 29 and

higherAndroid SDK r14 and higherEclipse 3.6 and higher

1.2. Distribution The SDK is distributed as a class library (in the form of a Java source tree within

an Android library project) which implements all provided functionality.

1.3. Required Knowledge This document was written for developers with previous experience developing

applications that use the Android SDK. For information on developing for Android, please consult the Android SDK reference provided by Google.

1.4. Guideline Compliance

GREE will provide a set of guidelines detailing how apps should use the GREE

SDK. This document is not available during this release, and will be made available as soon as possible.

Copyright © 2012 GREE, Inc. All Rights Reserved.6

Page 7: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

2. Before Beginning Development

This SDK to projects under development allows for simple use of the functionality provided by the GREE Platform. A library of API functions is provided for apps, and calling these functions as necessary allows developers to use the data and UI provided by the GREE Platform.

Please consult the GREE Platform Android SDK API Reference included with the

SDK for details about the APIs provided with this SDK.

2.1. Setting Up the GREE Sandbox The GREE Platform provides an environment, called the GREE sandbox, to test

newly-developed apps. Please consult the supplemental document, Using the Sandbox for details.

The following authentication keys are issued when registering an app for testing. These keys are required when implementing apps.

Authentication Key Description

CONSUMER_KEY The Consumer Key value issued by Developer Center (sandbox)

CONSUMER_SECRET The Consumer Secret value issued by Developer Center (sandbox)

APPLICATION_ID The App ID value issued by Developer Center (sandbox)

Copyright © 2012 GREE, Inc. All Rights Reserved.7

Page 8: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

3. Setting Up the Development Environment

This SDK assumes the use of a standard Eclipse-based Android app development environment. The information below assumes that Eclipse (English edition) and the Android SDK have already been set up.

3.1. Importing the Library 3.1.1. Downloading the SDK

Begin by downloading the GREE Platform Android SDK source code set from the

GREE Developer Center. The method of source code distribution may change at any time without previous notice.

3.1.2. Adding Project and SDK to Eclipse

Go to [File -> Import] and select [General -> Existing Projects into Workspace].

Import the "GreeSDK" , "signpost-commonshttp4" and "signpost-core" projects.

Copyright © 2012 GREE, Inc. All Rights Reserved.8

Page 9: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

3.1.3. Creating Application Project Go to [File -> New -> Android Project] to create a new Android project. Select

Android 2.3 or higher for the build target. Even if Android 2.3 is selected as the minimum SDK, the API level in the next screen can still be set to 7 to allow Android 2.1 devices to run the app.

Set up the application info. We will set the name to GreeHelloSample. We will not

create a test project for this app, so click on the "Finish" button.

3.1.4. Referencing the GREE SDK from the Project

Right-click on the project name in the Package Explorer and click on "Properties".

Open the Android menu, then add the GreeSDK library.

Copyright © 2012 GREE, Inc. All Rights Reserved.9

Page 10: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

Next, in order to add needed external libraries, open the "Java Build Path" menu and include the "gson-2.0jar" file, in the "libs" folder inside the GreeSDK project. Click on "OK" and close the Properties dialog.

3.2. Gadget XML

Gadget XML allows for the retrieval of lifecycle event data via HTTP requests.

Configuring Gadget XML is not necessary if lifecycle events are not being used. These documents are not yet available and will be provided as soon as possible.

Copyright © 2012 GREE, Inc. All Rights Reserved.10

Page 11: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

4. Building a Sample App

The following describes how to build a simple app that uses the functions provided in this SDK. After a GREE logo splash display, the app will display a sandbox authentication screen. After authentication is complete, the app will display "Hello World, GreeHelloSampleActivity".

4.1. Setting Up Initialization File

To begin with, we will set up a file in order to initialize the SDK. First, go to the "res" folder and create a folder named "xml".

Next, we will create an XML configuration file within this folder. This file is named

gree_platform_configuration.xml in this example.

<?xml version="1.0" encoding="utf-8"?><properties> <debug>true</debug> <app_name>GREEHelloSample</app_name> <app_fullname>GREE Hello Sample</app_fullname> <app_id>NNNN</app_id> <consumer_key>XXXXXXXXXXXX</consumer_key> <consumer_secret>XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</consumer_secret> <!-- Choose your server from here --> <gree_environment>sandbox</gree_environment> </properties>

● Set "debug" to "true" to enable debugging output.● "app_name" and "app_fullname" defines the name of the app.● "app_id", "consumer_key" and "consumer_secret": Insert the app ID, consumerKey

and consumerSecret here.-> These values are acquired when setting up the sandbox (section 2.2).

● "gree_environment": Set this to "sandbox" to enable access to the sandbox environment.

Copyright © 2012 GREE, Inc. All Rights Reserved.11

Page 12: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

4.2. Handling Initialization

In order to add the initialization code into the Application class, we will create an inheritor subclass, called GreeApplication here.

package net.gree.sample.GreeHelloSample; import net.gree.asdk.api.GreePlatform;import android.app.Application; public class GreeApplication extends Application { @Override public void onCreate() { super.onCreate(); apiInit(); } public void apiInit() { GreePlatform.initialize(getApplicationContext(), R.xml.gree_platform_configuration); }}

This GreePlatform.initialize function handles SDK initialization. The second argument

defines the XML file resource previously created.

4.3. Setting Up AndroidManifest.xml Next we will set up AndroidManifest.xml. Open the AndroidManifest.xml file for the app

created. This file is on the app side. Do not edit the one inside the SDK itself.

<activity android:name="net.gree.asdk.core.dashboard.DashboardActivity" android:configChanges="orientation" ></activity><activity android:name="net.gree.asdk.core.dashboard.ModalActivity" ></activity><activity android:name="net.gree.asdk.core.auth.SetupActivity" android:configChanges="orientation|keyboardHidden" android:theme="@android:style/Theme.Translucent" android:launchMode="singleTask"> <intent-filter > <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="greeappXXXX" android:host="register" /> </intent-filter></activity>

* "XXXX" is the app ID acquired when setting up the sandbox (section 2.2).

We will add the activity set provided by the SDK. The app is set up to connect to the sandbox environment. Connecting to the GREE Platform, including the sandbox, requires login authentication from the user. The SDK uses OAuth 1.0(RFC5849) for authentication, and net.gree.asdk.core.auth.SetupActivity has been added.

Copyright © 2012 GREE, Inc. All Rights Reserved.12

Page 13: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

Within the "application" element, the GreeApplication class implemented in the GREE SDK, along with inheritor classes, are declared.

<application android:name=".GreeApplication" android:icon="@drawable/ic_launcher" android:label="@string/app_name" ></application>

The following sections are also recommended.● "android:versionName" entry within "manifest" element

-> android:versionName="N.N.N"

● SD card installation settings in "android:installLocation" entry within "manifest" element-> android:installLocation=[ "auto" | "preferExternal" ]

● "android:minSdkVersion" entry within "manifest" element-> Set "android:minSdkVersion" to 7 or higher

Next, edit the app's "activity" element. Two URL schemes must be defined within

the element filter. Insert the app ID into the XXXX sections.

<activity android:label="@string/app_name" android:name=".GreeHelloSampleActivity" > <intent-filter > <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" />

<data android:scheme="greeappXXXX" android:host="start" /><data android:scheme="greeappopenXXXX" />

</intent-filter></activity>

Add the following device function permissions.

<uses-permission android:name="android.permission.WAKE_LOCK"/><uses-permission android:name="android.permission.GET_TASKS"/><uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/><uses-permission android:name="android.permission.READ_PHONE_STATE"/><uses-permission android:name="android.permission.RECEIVE_SMS"/><uses-permission android:name="android.permission.READ_SMS"/><uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/><uses-permission android:name="net.gree.Sample.permission.C2D_MESSAGE"/><uses-permission android:name="com.google.android.c2dm.permission.RECEIVE"/><permission

android:name="net.gree.Sample.permission.C2D_MESSAGE" android:protectionLevel="signature" ></ permission >(* Change "net.gree.Sample" to the package name of the app.)

Copyright © 2012 GREE, Inc. All Rights Reserved.13

Page 14: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

5. Testing Created Apps

Apps are tested in the sandbox environment. The following section describes the results generated.

5.1. Building a Developed App. First, clean the project via "Clean" off the Project menu. Next, right-click on the project in the Package Explorer and select [Run As ->

Android Application] to build and run the app.

5.2. Running the App on the Simulator If the build was executed successfully, the app will run in the Simulator.

Copyright © 2012 GREE, Inc. All Rights Reserved.14

Page 15: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

6. Calling Login/Logout Functions

6.1. Login Processing In this section, we will add login processing to the sample app, using the SDK to

communicate with the GREE Platform. Open the "GreeHelloSampleActivity.java" file for editing.

public class GreeHelloSampleActivity extends Activity {/** Called when the activity is first created. */@Overridepublic void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);setContentView(R.layout.main);

// Show Login Dialogif (!Authorizer.isAuthorized()) {

Authorizer.authorize(GreeHelloSampleActivity.this, new AuthorizeListener() {public void onAuthorized() { success("login"); }public void onCancel() { cancel("login"); }public void onError() { error("login"); }

});}

} private void success(String feature) { showResult(feature, "success"); }private void error(String feature) { showResult(feature, "error"); }private void cancel(String feature) { showResult(feature, "cancel"); }

private void showResult(String feature, String result) {

Toast.makeText(GreeHelloSampleActivity.this, feature+" "+result, Toast.LENGTH_SHORT).show();

}}

An "Authorizer.authorize" call is added to the "onCreate" function in

GreeHelloSampleActivity in order to summon the GREE Platform SDK login screen. Here, "if(!Authorizer.isAuthorized())" is added so the login screen is displayed only if

authentication has not succeeded in the past. After logging in once, login info is kept within the app until the user logs out, so there is no need to login every time the app is launched.

A new AuthorizeListener class is declared in order to set up callback processing

after the login is complete. Cases are set up for when authentication succeeds, is canceled, or if an error occurs. Code is also added to display login authentication results via Toast.

If processing is necessary on the app side when the user logs in, this can be

added to each of these callback functions.

Copyright © 2012 GREE, Inc. All Rights Reserved.15

Page 16: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

6.2. Logout Processing

Next, we will add logout processing to the app. In order to logout, a login button will first be added to the sample app. Open the "main.xml" file in the Layout folder of the resource files to add a login

button.

<?xml version="1.0" encoding="utf-8"?><?xml version="1.0" encoding="utf-8"?><LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="fill_parent" android:layout_height="fill_parent" android:orientation="vertical" > <TextView android:layout_width="fill_parent" android:layout_height="wrap_content" android:text="@string/hello" /> <Button android:id="@+id/buttonLogout" android:layout_width="match_parent" android:layout_height="wrap_content" android:text="Logout from GREE" /> </LinearLayout>

Open the "GreeHelloSampleActivity.java" file again and add code for when the logout

button is pressed. This code is placed before the code previously added.

// Logout ButtonButton aLogoutButton = (Button)findViewById(R.id.buttonLogout);aLogoutButton.setOnClickListener(new OnClickListener() {

public void onClick(View v) {AuthorizerCore.getInstance().revoke(GreeHelloSampleActivity.this,

new RevokeListener() {public void onRevoke() { success("logout"); }public void onCancel() { cancel("logout"); }public void onError() { error("logout"); }

});}

}); The "AuthorizerCore.getInstance().revoke" function is now called in order to complete

the logout. As before, a new RevokeListener class is declared in order to set up callback

processing after the logout is complete. Processing is defined for when a logout succeeds, is canceled, or if an error occurs. Code is also added to display logout authentication results via Toast. If processing is necessary on the app side when the user logs out, this can be added to each of these callback functions.

Copyright © 2012 GREE, Inc. All Rights Reserved.16

Page 17: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

6.3. Execution After cleaning the project again, rebuild and execute the app. A login screen will be displayed, as below.

Click on the "Let's Go" button, and a login-start screen is displayed. Enter the test user ID and password made in the sandbox to login.

If successful, the login screen will close and a "login success" Toast message is

displayed before returning to the app screen.

Copyright © 2012 GREE, Inc. All Rights Reserved.17

Page 18: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

Next, execute a logout. Press the logout button. The logout screen is displayed. Press the logout button to begin logout processing

and display the login screen again.

Copyright © 2012 GREE, Inc. All Rights Reserved.18

Page 19: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

Appendix: Error Message List

This is a list of the error messages displayed by the SDK, along with descriptions of what they mean.

A1. OAuth

Message(Error code)

Meaning/Things to check

Authentication failed. Please check your connection environment. [EC:O-04]

A communication error occurred during authentication. Check the following:・Network connection・Name of connecting server (public/sandbox)・Consumer Key / Secret values・Is the time on the device de-synced with the server?

Failed to create signature. Please contact the provider of the app.[EC:O-01]

Failed to create OAuth signature. Check the following:・Network connection・Name of connecting server (public/sandbox)・Consumer Key / Secret / App ID values

Authentication failed. Invalid authentication data. Please contact the provider of the app.[EC:O-02]

Authentication data did not match with the data on the server side. Check the following:・Name of connecting server (public/sandbox)・Consumer Key / Secret / App ID values・Is the App publicly available on GREE?

Unexpected value from server. Please try again later.[EC:O-03]

Something went wrong with the authentication process. There may be a communication error with the server, or the Consumer Key / Secret values may be invalid.

Copyright © 2012 GREE, Inc. All Rights Reserved.19

Page 20: GREE Platform Android SDK Ver. 3.0.0 α Developer's Guide · 2015-08-25 · GREE Platform Android SDK version SDK Version GREE Platform Android SDK 3.0.0 α Development environment

A2. Initialization / Misc.Message Meaning/Things to check

Failed to initialize app. Cannot start.[Initialization error]

The app failed to initialize upon launch. Check that the keystore library is in the right place and that everything in greeappinfo.h is correct. The value of APPLICATION_SIGNATURE, in particular, may be incorrect.

Network communication failed. Cannot start.[Communication error]

A network error occurred during app initialization, making the initialization fail. Check your net connection and whether you have the right server name.

An unknown error occurred. Cannot start.

Please contact a GREE support representative if this occurs. Include a copy of the console log.

Copyright © 2012 GREE, Inc. All Rights Reserved.20