1. About Zirconia for ANDROID ....................................................................................................... 3 1) Overview ................................................................................................................................... 3 2) License Inspection Process ...................................................................................................... 3 2. Procedures before using Zirconia for ANDROID ......................................................................... 3 1) Adding JAR ............................................................................................................................... 4 2) Add JIN Native Library .............................................................................................................. 4 3) Add Permission......................................................................................................................... 5 4) Coding instructions ................................................................................................................... 5 3. Application Procedure of Zirconia for ANDROID ......................................................................... 6 4. Appendix About Zirconia for ANDROID API .............................................................................. 7 1) Package com.samsung.zirconia ............................................................................................... 7 2) Interface LicenseCheckListener ............................................................................................... 8 3) Class Zirconia ........................................................................................................................... 8 4) Class ZirconiaVersion ............................................................................................................. 10
Confidential Samsung Electronics 3 1. About Zirconia for ANDROID
1) Overview As a library providing preventive measures against illegal reproduction, Zirconia for ANDROID can be used in Samsung Mobile devices. This library is supplied as a form of Java package that can be used in ANDROID development environments and includes JNI Native Library (*.so). Zirconia inspects the license of applications being executed to prevent illegal use. Zirconia checks for license from the license server upon the initiation of an application and stores it in device. It also checks for license from the server if the stored license has been removed or damaged. The license from the server is unique for each device and application. Therefore, when an application in a certain device is reproduced into another device, the application will not be executed correctly.
2) License Inspection Process
Zirconias interior action process for checking a license is as below:
Zirconia makes an inquiry to check for a license stored at a device. If a valid license is identified, a restriction for the application use will be removed. When a license does not exist or is not valid, the information of the device and application will be sent to the license server. (Once license is stored in the storage device, internet connection is not required anymore.) If the application has been purchased for use in the device, the license server transmits the license back to Zirconia of the device. Zirconia stores the received license into a storage device. Return to Step .
The above procedures are automatically carried out by Zirconia and the user is not involved.
2. Procedures before using Zirconia for ANDROID
Several preliminary procedures are required before using the library of Zirconia for ANDROID Package JAR and JNI Native Library should be added to the project, followed by addition of the manifest permission. For details, please refer to the following section.
Confidential Samsung Electronics 4 1) Adding JAR
File configuration of Zirconia for ANDROID includes Zirconia.jar, a JAR file, and libnativeinferface.so, JIN Native Library. First, add Zirconia.jar to the Android application project. The following figure shows an example of Eclipse Project.
Figure 2. Add JAR to application project
2) Add JIN Native Library
Create a folder, "libs/armeabi," under the project route path, and copy and place libnativeinterface.so, a JNI Native Library, into the folder. The following figure shows an example of Eclipse Project.
To inspect the validity of a license and to make an inquiry of license check to the server, Zirconia for ANDROID needs device information and internet connection. For this purpose, permission for READ_PHONE_STATE and INTERNET should be added to the manifest of the application. See example in figure below.
Figure 6. Adding permission to the manifest of the application project
4) Coding instructions
Do not repeatedly and excessively call the Zirconia.checkLicense() method. Though Zirconia is not oversized, it uses File I/O, Encoding/Decoding, and Internet Communication to make an inquiry and storage. When Zirconia.checkLicense() method is called repeatedly, a lot of internal threads will be created, and resources will be wasted. For example, if this function is called by a frequently operated action handler, application performance may be influenced due to continual actions of File I/O and Encoding/Decoding.
Create a short Zirconia action listener method. Basically, Zirconia does not return license validity inspection results in boolean. Zirconia.checkLicense() works asynchronously, and the method of the listener object is called when the license validity inspection is terminated. Internal thread of Zirconia will survive while the action listener method is working, so the action listener method should be terminated first in
Confidential Samsung Electronics 6 order to end this thread.
Zirconia may not work well if the device's network is offline or in airplane mode. Therefore, users are advised to activate the device's network before the application initializes Zirconia.
3. Application Procedure of Zirconia for ANDROID
Though Zirconia for ANDROID is composed of several classes, only Zirconia is actually in use. In this class, few methods exist, and their operation methods are relatively simple. Coding procedures for the application of Zirconia are as below:
Create an object of Zirconia class. Prepare a class inheriting the LicenseCheckListener interface. Create an object of the class prepared in Step 2, and transfer it to the object created in Step 1 through Zirconia.setLicenseCheckListener() method. License validity inspection and inquiry are carried out by calling Zirconia.checkLicense(). This process may be repeated several times; the method of the listener object created in Step 3 is called when the license verification is completed. Each step of the above procedures can be implemented at any stage in the application. For example, the above procedure can be implemented at the game initiation stage if you want to prohibit the usage of the entire stage by a user without purchasing the game application. Otherwise, it can also be implemented at the end of the first stage if only the first stage needs to be opened.
See the following sample code: package com.samsung.zirconia.test;
/* Listener class to receive the results of license verification and inquiry */ class MyLicenseCheckListener implements LicenseCheckListener {
/* In case the results of license verification and inquiry are normal */
Confidential Samsung Electronics 7 @Override public void licenseCheckedAsValid() { Log.d("ZirconiaTest", "License is valid");
ownerHandler.post(new Runnable() { public void run() { ownerTextView.setText("License is valid"); } }); }
/* In case the results of license verification and inquiry are abnormal */ @Override public void licenseCheckedAsInvalid() { Log.d("ZirconiaTest", "License is invalid");
ownerHandler.post(new Runnable() { public void run() { ownerTextView.setText("License is invalid"); } }); }
Handler ownerHandler; TextView ownerTextView; }
public class ZirconiaTest extends Activity {
/** Called when the activity is first created. */ @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState);
Handler handler = new Handler(); TextView tv = new TextView(this); tv.setText( "This is a simple test application for Zirconia!\nPlease hold on while verifying the license..." ); setContentView(tv); //setContentView(R.layout.main);
/* Create object * The first factor is the Application's Activity object in progress. */ Zirconia zirconia = new Zirconia(this);
/* Create a listener object , * register the listener object to the Zirconia object, and * inspect the license. */ MyLicenseCheckListener listener = new MyLicenseCheckListener(); listener.ownerHandler = handler; listener.ownerTextView = tv; zirconia.setLicenseCheckListener(listener); zirconia.checkLicense(false, false); } }
4. Appendix About Zirconia for ANDROID API
1) Package com.samsung.zirconia
Confidential Samsung Electronics 8 com.samsung.zirconia is a Java package that provides the function of Zirconia for ANDROID. This package opens one interface and two classes to the external party as below:
Interface Summary LicenseCheckListener Listener interface to receive the results of license verification and inquiry
Summary of Class Zirconia Class that provides main functions of Zirconia ZirconiaVersion Class that indicates the version of Zirconia
2) Interface LicenseCheckListener This listener interface is called when the license verification and inquiry are completed. The interface can be implemented by a class internally that needs to know the validity of license. After creating an object, the results can be received once the object is transferred to the factor of Zirconia's method Zirconia.setLicenseCheckListerner(). After the verification procedure is completed, Zirconia calls an appropriate method of the object.
Method void licenseCheckedAsInvalid() It is called when the license is not valid. void licenseCheckedAsValid() It is called when the license is valid.
3) Class Zirconia
As the core class of Zirconia for ANDROID, it carries out the license verification and inquiry functions.
Field static int EZIRCONIA_KEY_CREATION_FAILED The license cannot be stored in the device. Error in the storage device or the license. static int EZIRCONIA_LICENSE_MISMATCH Verification and/or inquiry of the license cannot be made due to errors in server or storage device. static int EZIRCONIA_NOT_PURCHASED The user has not purchased this application. static int EZIRCONIA_RECEIVE_FAILED License inquiry to server cannot be made due to errors in network or server. static EZIRCONIA_SEND_FAILED License inquiry to server cannot be made due to errors in network or server.
Confidential Samsung Electronics 9 int static int EZIRCONIA_SERVER_MISMATCH License inquiry to server cannot be made due to errors in server. static int EZIRCONIA_SUCCESS Success.
Constructor Zirconia(Activity activity) Zirconia object is created and returned.
Method void checkLicense(boolean checkLocalOnly, Boolean dontUseThread) Calls a suitable method of the listener LicenseCheckListener object after verification and inquiry of the application's license. When this method is called, it inspects the license stored in the storage device. If valid license exists, the licenseCheckedAsValid() method of the listener object is called. If the license does not exist or is not valid, an inquiry of license to server is made. After the inquiry, the license is stored in the device, and the stored license is verified. If the license cannot be attained from the server, the licenseCheckedAsInvalid() of the listener object is called. If the license stored locally is valid before calling this method or the first factor of this method, checkLocalOnly, is true, no connection to the server is made. The setLicenseCheckListener() method must be called before calling this method to register the listener object. Factor: checkLocalOnly If this factor is true, a license inquiry to the license server is not made even if no valid license exists in the device. dontUseThread If this factor is true, the results of license verification and inquiry are directly returned without using internal thread and listener. boolean deleteLicense() Deletes the stored application license in the device. int getError() Returns recent error codes. Please refer to the summary of constant. boolean isWorking() Checks if the checkLicense() method is working. void setBogusIMEI(String bogusIMEI) A method used when a development is in progress in the emulator. Sets IMEI temporarily. It does not work in the actual device, so that it must be removed from the code prior to the release. Factor: bogusIMEI temporary IMEI void setLicenseCheckListener(LicenseCheckListener listener) Registers a listener that returns the results of license verification and inquiry. It must be called before calling the checkLicense() method. Factor: listener - Listener object to receive the results of license verification and inquiry void setThreadPriority(int newPriority) Sets the priority of thread that verifies and inquires a license. Factor: newPriority Priority of thread. A point between 1 and 10 can be selected if
Confidential Samsung Electronics 10 5 is the default value. ZirconiaVersion version() Returns the library version of Zirconia.
4) Class ZirconiaVersion
It is the class that indicates the version of Zirconia. It is used to have a returning value by calling Zirconia.version().
Field int build Build version int major Major version int minor Minor version