Server Side Integration

Before you integrate your backend code with Kachingle, make sure your front-end code is using the Kachingle Javascript API necessary to keep track of Subscribers status.

The Kachingle Premium PHP class allows you to retrieve information about your application and bundles, as well as interact with the Subscriber cookie.

Instantiating the class

On the sandbox:

<?php
$kachingle_api = new Kachingle(Kachingle::use_sandbox);
?>

In production:

<?php
$kachingle_api = new Kachingle(Kachingle::use_live_www);
?>

Retrieving the Subscriber’s information and status

$kachingle_api->check_premium_status($your_app_id, $your_app_secret) returns critical information about the Subscriber in the session using an associative array.

<?php
$user_status = $kachingle_api->check_premium_status($your_app_id, $your_app_secret);
?>

Arguments

$app_id	Integer. App ID you recorded when creating your Medallion. How to obtain the value is described in Development Process.
$app_secret	String. App secret recorded when creating your Medallion. How to obtain the value is described in Development Process.

Return Value

This method returns an associative array with the following keys:

Key	Value	Note
app_id	Integer This is an identifying number that corresponds to your Medallion and identifies your App in API calls.	Only present if user_is_known=1.
medallion_is_turned_on	Boolean (1 or 0) Indicates whether a visiting Subscriber is kachingling your App.	If the flag is set to 1, the Subscriber is kachingling your App, and should be provided premium features.
user_id	Integer ID of the Subscriber.
user_name	String. Username of the Subscriber.
user_is_known	Boolean (1 or 0) Indicates whether the Subscriber has a Kachingle account and is logged in to the Medallion.
user_is_subscribed	Boolean (1 or 0) Indicates whether the Subscriber is subscribed to any Kachingle Bundle that includes this Medallion (i.e., your App).	The Subscriber is subscribed to a Bundle that includes your App. However, the Subscriber may not be kachingling your App. To know that, use the value for the medallion_is_turned_on key.
bundles	Array of integers IDs of the Kachingle Bundles that contain your App, and to which the Subscriber is subscribed.	When the value of user_is_subscribed is 0, this array is empty.

Mapping the Subscriber's status to your application's session

From the developer's/vendor's perspective, a user can be in one of five states:

1. Logged Out - These are users that either:
   • Are Kachinglers, but are not logged into the Medallion (there is no Kachingle cookie on their browser)
   • Are not Kachinglers
   You will want to encourage these users to sign up with Kachingle (by using the Join API) to get your App's premium features. (Kachinglers who are logged out can login from the Medallion.)
2. Logged In - Kachinglers who are logged in, but are not subscribed to any Bundle that includes your App. These users should be encouraged to subscribe via the Join API.
3. Subscribed - These are Kachinglers that are subscribed to at least one Bundle that features your app, but are not yet kachingling your app. These Kachinglers just need to start kachingling your App, which can be done through the Medallion embedded in your pages.
4. Kachingling - These are Kachinglers who are subscribed to a Bundle containing your App, and have kachingling turned on. These Kachinglers should be provided access to your premium features.
5. Recently Unsubscribed - When a Kachingler unsubscribes from any/all Bundles that contain your App, they should still receive premium features until the end of their payment cycle. You may wish to ask why he or she has unsubscribed, or encourage them to re-subscribe.
   

The relationship between the five kinds of users and the values that are returned in the check_premium_status() function are summarized in the following table.

	user_is_known	user_is_subscribed	medallion_is_turned_on	Example Medallion
Logged Out	0	0	0
Logged In	1	0	0
Subscribed	1	1	0
kachingling	1	1	1
Recently Unsubscribed	1	0	1

Retrieving Information About a Medallion

The $kachingle_api->get_app($your_app_id) method returns an instance of the App class corresponding to the $app_id argument.

<?php
$kachingle_api = new Kachingle(Kachingle::use_sandbox);
$app = $kachingle_api->get_app($app_id);
?>

The App instance contains many details that are accessible through the following methods:

App Instance Methods	Return Value
$app->logo()	String. URL of the App's logo image stored on the Kachingle servers.
$app->name()	String. Name of the App.
$app->bundles()	Array of integers. Returns an array containing the IDs of all bundles that feature the App.

Retrieving Information About a Bundle

The $kachingle_api->get_bundle($bundle_id) method returns an instance of the Bundle class corresponding to the $bundle_id argument.

<?php
$kachingle_api = new Kachingle(Kachingle::use_sandbox);
$bundle = $kachingle_api->get_bundle($bundle_id);
?>

The details of a Bundle are accessible through the following method of the Bundle instance:

Bundle Instance Methods	Return Value
$bundle->price()	Decimal. Price of the Bundle.
$bundle->duration()	String. Length of time between Bundle subscription payments.
$bundle->name()	String. Name of the Bundle.
$bundle->apps()	Array of Integers. Array of the IDs of the Apps that are contained in the Bundle.
$bundle->type()	String. Returns one of the two following strings: - "set_of_apps" for Bundles in which all apps can be kachingled at once - "roll_your_own" for Bundles with a limited number of "points," with apps assigned point values
$bundle->can_user_kachingle_app($user_id, $your_app_id)	Boolean. Determines whether the Subscriber that is specified by $user_id has enough points remaining in a "roll your own" Bundle to begin kachingling the App specified by $app_id. Returns true if the Subscriber has enough points, false otherwise.

Join API

To register new Kachinglers for your App without the Kachingle Medallion, you will direct them to the Kachingle join page.

The URL of that page is easily built through the get_join_url method of the Kachingle class.

<?php
$kachingle_api = new Kachingle(Kachingle::use_sandbox);
$url = $kachingle_api->get_join_url($your_app_id, $featured_bundle_id);
echo "<a href=â$urlâ>Register</a>";
?>

Arguments

$your_app_id	Integer. App ID you recorded when creating your Medallion.
$featured_bundle_id	Integer. Optional. The ID of the Bundle you want to promote to the new Kachingler as they create their account. When supplied, the Kachingle join page will be branded with your App and highlight your chosen Bundle. When not supplied, the join page will show all Bundles containing your App, but without any particular Bundle highlighted.

Return Value

String. URL of the registration page.

« Previous: Client Side Integration Next: Demo »