Tizen Store

Implementing a Store

CloudMoolah MOO store

Like the Apple App Store and the Google Play Store, the CloudMoolah MOO Store is a commercial online service that enables people to buy and sell mobile apps as well buy items in the application (known as ‘in-app purchasing’ or ‘IAP’).

The MOO Store serves Asian markets. Users maintain a digital wallet, which they can top up using a variety of payment providers, such as banks and convenience store pre-paid cards.

Although compatible with Unity, the CloudMoolah MOO Store is not a Unity product. For more information, see documentation on configuring for CloudMoolah MOO Store or visit the CloudMoolah Developer Portal website at dev.cloudmoolah.com.

This documentation lists the functionality you need to use and describes the implementation via Scripting API using Unity API and CloudMoolah API.

Sample implementation

Unity IAP’s default integration includes an implementation script example that demonstrates how to use both of the required - and some of the optional - CloudMoolah scripting APIs.

To see the CloudMoolah-specific example:

Go to the Assets/Plugins/UnityPurchasing/script folder.
Find the example file: IAPDemo.cs and open it.
In IAPDemo.cs, search for the following APIs: IMoolahConfiguration and IMoolahExtension.

The IMoolahConfiguration API’s appKey and hashKey are set in the IAPDemo.cs file’s Awake() function. This connects your app with the Store backend.

The IMoolahExtension API’s FastRegister and Login functions are defined in the IAPDemo.cs file’s InitUI function. The FastRegister and Login functions are called when a game player taps buttons on the GUI that corresponds to them.

IAPDemo.cs file also includes optional API for configuring test mode, and for extending functionality to include transaction restoration - see the API definitions below for more information.

Initialization prerequisites

An app targeting the CloudMoolah MOO Store must configure the CloudMoolah appKey and hashKey using the IMoolahConfiguration via the scripting API before initializing Unity IAP. Collect these variables’ values from the app’s CloudMoolah developer dashboard.

// Configure initialization prerequisites from within an IStoreListener implementation
var module = StandardPurchasingModule.Instance();
var builder = ConfigurationBuilder.Instance(module);
builder.Configure<IMoolahConfiguration>().appKey = "d3d3cd207594ee1bd93f4564c41d463e";
builder.Configure<IMoolahConfiguration>().hashKey = "my-hash-key";
// May now initialize UnityIAP with UnityPurchasing.Initialize(this, builder)

Configuration API

Unity IAP supports pre-initialization store-specific scripting API through a configuration mechanism.

Access the IMoolahConfiguration instance with IMoolahConfiguration moolahConfiguration = ConfigurationBuilder.Configure<IMoolahConfiguration>(). See Purchasing.ConfigurationBuilder.Configure for more on using accessing Unity IAP configuration APIs.

appKey

The appKey is your game’s unique identifier, and is generated by the CloudMoolah server when you register a new app.

Syntax

string IMoolahConfiguration.appKey

Description

Required to initialize.
Uniquely identifies the game.
Apply for this on the CloudMoolah Developer Portal.
Set before initialize is called.

Example

var builder = ConfigurationBuilder.Instance(StandardPurchasingModule.Instance());
 
builder.Configure<IMoolahConfiguration>().appKey = "d3d3cd207594ee1bd93f4564c41d463";

hashKey

The hashKey uniquely identifies your game when it is defined in the CloudMoolah MOO Store, and helps to secure the connection between a client app and the server’s store.

The appKey is your game’s unique identifier, and is generated by the CloudMoolah server when you register a new app.

Syntax

string IMoolahConfiguration.hashKey

Description

Required to initialize.
Apply for this on the CloudMoolah Developer Portal.
Uniquely identifies the game, and is defined by the developer.
Set before initialize is called.

Example

var builder = ConfigurationBuilder.Instance(StandardPurchasingModule.Instance());
 
builder.Configure<IMoolahConfiguration>().hashKey = "my-hash-key";

Extensions API

Unity IAP supports post-initialization store-specific Scripting API through an extension mechanism.

Acquire the IMoolahExtension interface instance for CloudMoolah through the IExtensionProvider that the IStoreListener.OnInitialized API returns on initialization.

Capture the IMoolahExtension instance with:

private IMoolahExtension m_MoolahExtensions;
public void OnInitialized(IStoreController controller, IExtensionProvider extensions)
{
    m_MoolahExtensions = extensions.GetExtension<IMoolahExtension> ();
}

Note: Restore non-consumable transactions (see documentation) through this store-specific Scripting API extension.

Purchasing prerequisites: registration and login

The CloudMoolah wallet collects real currency from pre-paid cards and SMS payments. Transactions use the currency in the wallet during the payment process.

As such, CloudMoolah must establish per-user identification through registration and login to create and access a user’s digital wallet.

Registration

There are two ways to perform user identification without user involvement: create an app that registers and logs in using computer-generated credentials, or an app that shares previously-created credentials from a third-party identity service. This results in the creation of more secure identifiers; for example, a string of randomly generated letters and numbers, rather than something less secure or possibly duplicated, such as the user’s real name.

In some cases, standalone or offline games might not have access to an identity service from a game developer or publisher. In this instance, you may want to generate user credentials. Register using the result of Unity’s SystemInfo.deviceUniqueIdentifier API, and supply this as the user-identifying “password”. Note that when you use this API, it automatically adds the android.permission.READ_PHONE_STATE to an Android app’s manifest.

Another situation is online games. A game player might have an online identity service available to them through their game server. In this case, you need to copy user-identifying credentials as the registration password.

Note: The registration password must remain constant over the lifetime of the user account, serving as a permanent access token for that particular user’s wallet.

Login

Purchasing requires a successful login, which requires a user to register.

The registration API only needs the user to provide a single password, which then creates the digital wallet. Registration also generates a username, which the API passes back to the client, and must be used in order for the user to log in.

The user must perform login once per session, and requires the generated username and user-identifying password. After the user logs in, they can add money to the wallet through the MOO Store’s supported payment providers, and can then attempt purchases.

For users to permanently bind a wallet to an email address, they must supply additional identifying credentials (such as a phone number) to the CloudMoolah web service during the purchase process on their Android device.

Register for a digital wallet

Syntax

void IMoolahExtension.FastRegister(string CMpassword, Action<string> registerSuccessed, Action<FastRegisterError, string> registerFailed)

Parameters

CMpassword: User-defined password for signing up with the CloudMoolah user system.
registerSuccessed: Passes (string cmUserName) on successful fast registration (see below).
registerFailed: Passes error code and string description when fast registration fails.

Description

Required for purchase.
The FastRegister function returns a username generated by CloudMoolah to access a CloudMoolah digital wallet. The user can later perform a full registration in the CloudMoolah purchasing web service to permanently bind the wallet to them through their phone number.
Called after initialization.

Example

// Use custom password to register a CloudMoolah acount.
m_MoolahExtensions.FastRegister("CMPassword", registerSucceed, registerFailed);
 
public void registerSucceed(string cmUserName)
{
    m_CloudMoolahUserName = cmUserName;
    Debug.Log ("registerSucceed : cmUserName is " + cmUserName);
}
 
public void registerFailed(FastRegisterError error, string errorMsg)
{
    Debug.Log ("registerFailed :FastRegisterError is " + error.ToString() + ", errorMsg is " + errorMsg);
}

Log in to an existing wallet

Syntax

void IMoolahExtension.Login(string CMUserName, string CMPassword, Action<LoginResultState, string> LoginResult)

Parameters

CMUserName: Returned from previous call to FastRegister (see below).
CMpassword: Used in previous call to FastRegister (see below).
LoginResult: Required. Passes (LoginResultState) attempt result along with (string message) diagnostic message.

Description

Required.
User logs in with their CloudMoolah username.
All standalone games can use the Unity GUID as a username. This allows users to make purchases without this login.

Example

m_MoolahExtensions.Login(m_CloudMoolahUserName, "CMPassword", loginResult);
 
public void loginResult(LoginResultState state, string message)
{
    m_IsLoggedIn = state == LoginResultState.LoginSucceed;
}

Testing

CloudMoolah supports local testing for checking an app’s purchase flow error handling, and for simulating payment without making a real-currency payment.

Configure developer mode

Syntax

void IMoolahExtension.SetMode(CloudMoolahMode mode)

Parameters

mode: Type of purchase flow to perform.

Description

Supply CloudMoolahMode to enable success, failure, or normal operation.

Example

m_MoolahExtensions.SetMode(CloudMoolahMode.AlwaysFail); // TESTING: all purchases fail

Additional API

Restore previous purchase transactions

Syntax

void IMoolahExtension.RestoreTransactionID(Action<RestoreTransactionIDState> result)

Parameters

result: The status of the transaction.

Description

Return all unfinished transactions which have been successfully paid for but have not been paid out yet (see the RequestPayOut Scripting API below).
Must be called after initialization.
Must first call login.

Example

// Retrieve transaction identifiers, when Client does not already have transaction identifiers.
 
m_MoolahExtensions.RestoreTransactionID(( RestoreTransactionIDState restoreTransactionIDState)=>{
    // Restore complete, see ProcessPurchase for restored products
};

Completely finish or consume transaction

Syntax

void IMoolahExtension.RequestPayOut(string transactionId, Action<string, RequestPayOutState, string> result)

Parameters

transactionId: Transaction identifier to finish.
result: TransactionId, the result of payout, or any error message.

Description

This is key for the delivery of a virtual item. It is helpful or necessary for offline games. Use this API after delivery of the virtual item.
Use this in instances where payment is successful but the game quits before the delivery of the virtual item is complete. The standalone game developer has no record of this, so they must call IMoolahExtension.RestoreTransactionID and then IMoolahExtension.RequestPayOut to finish the transaction.
For online games, you can manage payout yourself so the client does not need to call the IMoolahExtension.RequestPayOut operation and restore. The client’s game server can also return the delivery status while the server makes a callback, to do the IMoolahExtension.RequestPayOut operation.
Call this in ProcessPurchase.

Example

For an offline game from within ProcessPurchase:

// If platform is CloudMoolah, you should do payout on a standalone game and "return PurchaseProcessingResult.Pending" at the end.
 
if (m_IsCloudMoolahStoreSelected) {
    m_MoolahExtensions.RequestPayOut (m_CloudMoolahTransactionID, (string transactionID, RequestPayOutState state, string message) => {
        msg = "ProcessPurchase requestPayOut TannsationID:" + transactionID + ",state:"+ state.ToString() + ",msg:" + message;
 
        if (state == RequestPayOutState.RequestPayOutSucceed) {
            // Finish Transaction
                    m_Controller.ConfirmPendingPurchase(e.purchasedProduct);
            //payout success, issue virtual props. 
        } else {
            //PayOut Failed , Don't issue virtual props.
        }
    });
}
 
// You should unlock the content here.
// Indicate we have handled this purchase, we will not be informed of it again.
// If platform is CloudMoolah, you should "return PurchaseProcessingResult.Pending" on a standalone game or "return PurchaseProcessingResult.Complete" on an online game.
 
return PurchaseProcessingResult.Pending;

For an online game:

// You should unlock the content here.
// Indicate we have handled this purchase, we will not be informed of it again.
// If platform is CloudMoolah, you should "return PurchaseProcessingResult.Pending" on a standalone game or "return PurchaseProcessingResult.Complete" on an online game.
 
return PurchaseProcessingResult.Complete;

Validate receipt on the server

Syntax

void IMoolahExtension.ValidateReceipt(string transactionId, string receipt, Action<string, ValidateReceiptState, string> result

Parameters

transactionId: The payment transaction ID.
receipt: Receipt data returned through ProcessPurchase.
result: transactionId, enumeration of status, or an error message.

Description

Validate a transaction on the CloudMoolah server.
Call after a payment.

Example

// Validate a receipt on the server.
 
m_MoolahExtensions.ValidateReceipt(m_CloudMoolahTransactionID, m_CloudMoolahReceipt, (string transactionID, ValidateReceiptState state, string msg)=>{
    bool succeeded = state == ValidateReceiptState.ValidateSucceed;
});

Constants and enumerations

AndroidStore: addition of CloudMoolah

Syntax

public enum AndroidStore

New member

CloudMoolah: The CloudMoolah MOO Store’s Android identifier.

Description

Indicates the CloudMoolah MOO Store is active for Unity IAP.
Gets this from the standardPurchasingModule’s androidStore field.

Example

// Determine whether we are using CloudMoolah IAP. 
 
bool m_IsCloudMoolahStoreSelected = Application.platform == RuntimePlatform.Android && module.androidStore == AndroidStore.CloudMoolah;