Gameball Python SDK

---

The Gameball Python SDK provides convinient access to the Gameball API frpm applicatopns written in the Python langauage.

Documentation

---

Please refer to the Gameball API docs.

Installation

---

You don't need this source code unless you want to modify the SDK. If you just want to use the SDK, just run:

pip install gameball

Requirements

• Python 3.4+ (PyPy supported)
• Requests library 2.20 and later

Usage

---

The SDK needs to be configured with your account's API & Transaction keys available in your Gameball Dashboard

import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

Commands:

# creates a new player with the given player attributes.
gameball.initialize_player(player)

# performs action based on event triggered by users.
gameball.send_event(event)

# refers a new user through player with the given player code.
gameball.create_referral(referral)

# obtains player's balance value.
gameball.get_player_balance(player_unique_id)

# holds a specific amount of points from the player’s points balance. 
gameball.hold_points(player_unique_id, amount, transaction_time)

# enables the player to use Gameball points as a payment method since it can be substituted for monetary values.
gameball.redeem_points(player_unique_id, amount, transaction_time, hold_reference, transaction_on_client_system_id) 

# cancels a purchase reward or refund a points redemption transactions in Gameball.
gameball.reverse_transaction(player_unique_id, transaction_time, transaction_on_client_system_id, reversed_transaction_on_client_system_id)

# cancels previously held points identified by the given hold reference.
gameball.reverse_hold(player_unique_id, hold_reference, transaction_time) 

# rewards a player with points equivalent to the given amount.
gameball.reward_points(player_unique_id, amount, transaction_time, transaction_on_client_system_id, player_attributes = {})

# obtains player's information.
gameball.get_player_info(player_unique_id, lannguage= None)

# performs action based on event triggered by users or transactions.
gameball.send_action(action)

# create discount coupon to a specific user
gameball.create_discount_coupon(coupon)

# redeems discount coupon by a specific user
gameball.redeem_discount_coupon(player_unique_id, code, transaction_time)

# validates discount coupon by a specific user
gameball.validate_discount_coupon(player_unique_id, code, transaction_time)

Examples

Sending an Event Example

# Example 1
import gameball
gameball.api_key = "gb_test_..."

event_request = gameball.eventObject(player_unique_id= "player123")
event_request.add_event("place_order",
    {"total_amount":100,
        "category":[
        "electronics",
        "cosmetics"]
    }
)
event_request.add_event("review")
send_event_response = gameball.send_event(event_request)


# Example 2
import gameball
gameball.api_key = "gb_test_..."

event_request = gameball.eventObject(player_unique_id= " player123")
event_request.add_event("reserve", {"rooms" : 2})
event_request.add_player_attribute("displayName", " Jon Snow")
event_request.add_player_attribute("email", "jon.snow@example.com")
event_request.add_player_attribute("dateOfBirth", "1980-09-19T00:00:00.000Z")
event_request.add_player_attribute("joinDate","2019-09-19T21:06:29.158Z")
send_event_response = gameball.send_event(event_request)


# Example 3
import gameball
gameball.api_key = "gb_test_..."

event_request = gameball.eventObject(player_unique_id= " player123")
event_request.add_event("reserve", {"rooms" : 2})
event_request.add_player_attribute("displayName", " Jon Snow")
event_request.add_player_attribute("email", "jon.snow@example.com")
event_request.add_player_attribute("dateOfBirth", "1980-09-19T00:00:00.000Z")
event_request.add_player_attribute("joinDate", "2019-09-19T21:06:29.158Z")
event_request.add_custom_player_attribute("location", "Miami")
event_request.add_custom_player_attribute("graduationDate", "2018-07-04T21:06:29.158Z")
event_request.add_custom_player_attribute("isMarried", False)
send_event_response = gameball.send_event(event_request)

Create a Referral Example

# Example 1
import gameball
gameball.api_key = "gb_test_..."

referral_request = gameball.referralObject(player_code = "CODE11", player_unique_id = "player456")
referral_response = gameball.create_referral(referral_request)


# Example 2
import gameball
gameball.api_key = "gb_test_..."

referral_request = gameball.referralObject(player_code = "CODE11", player_unique_id = "player456")
referral_request.add_player_attribute("displayName", " Tyrion Lannister")
referral_request.add_player_attribute("firstName", "Tyrion")
referral_request.add_player_attribute("lastName", "Lannister")
referral_request.add_player_attribute("email", "tyrion@example.com")
referral_request.add_player_attribute("gender", "M")
referral_request.add_player_attribute("dateOfBirth", "1978-01-11T00:00:00.000Z")
referral_request.add_player_attribute("joinDate", "2019-09-19T21:06:29.158Z")
referral_request.add_custom_player_attribute("location", "Miami")
referral_request.add_custom_player_attribute("graduationDate", "2018-07-04T21:06:29.158Z")
referral_request.add_custom_player_attribute("isMarried", False)
referral_response = gameball.create_referral(referral_request)

Reward Examples

#Example 1
import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

reward_request = gameball.rewardObject(player_unique_id= "player123", amount= 99.98, transaction_id= "tra_123456789")
reward_response = gameball.reward_points(reward_request)


#Example 2
import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

reward_request = gameball.rewardObject(player_unique_id= "player456", amount= 2500, transaction_id= "tra_123456789")
reward_request.add_player_attribute("displayName", " Tyrion Lannister")
reward_request.add_player_attribute("firstName", "Tyrion")
reward_request.add_player_attribute("lastName", "Lannister")
reward_request.add_player_attribute("email", "tyrion@example.com")
reward_request.add_player_attribute("gender", "M")
reward_request.add_player_attribute("dateOfBirth", "1978-01-11T00:00:00.000Z")
reward_request.add_player_attribute("joinDate", "2019-09-19T21:06:29.158Z")
reward_request.add_custom_player_attribute("location", "Miami")
reward_request.add_custom_player_attribute("graduationDate", "2018-07-04T21:06:29.158Z")
reward_request.add_custom_player_attribute("isMarried", False)
reward_response = gameball.reward_points(reward_request)

Get Player Balance Example

import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

balance_response = gameball.get_player_balance(player_unique_id= "player456")

Hold Points Example

import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

hold_response = gameball.hold_points(player_unique_id= "player456", amount= 98.89)

Redeem Example

import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

redeem_response = gameball.redeem_points(player_unique_id= "player456",
                                        hold_reference= "2342452352435234", transaction_id= "tra_123456789")

Reverse Transaction Example

import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

reverse_transaction_response = gameball.reverse_transaction(player_unique_id= "player456",transaction_id= "1234567890",
                                                            reversed_transaction_id= '234567891')

Reverse Hold Example

import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

reverse_hold_response = gameball.reverse_hold(player_unique_id= "player456", hold_reference= "9245fe4a-d402-451c-b9ed-9c1a04247482")

Sending an Action Example

# Example 1
import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

action_request = gameball.actionObject(player_unique_id= "151515")
action_request.add_player_attribute("displayName", "Python_v2")
action_request.add_player_attribute("name","Mohamad")
action_request.add_points_transaction(transaction_id= "810008204529", reward_amount= 20)
action_response = gameball.send_action(action_request)


# Example 2
import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

action_request = gameball.actionObject(player_unique_id = "151515")
action_request.add_event("place_order", {"total_price":1500})
action_request.add_event("view_product_page")
action_request.add_points_transaction(transaction_id= "810008204529", hold_reference="1f306d48-706d-4e26-aeac-b3718ae7e5e2")
action_response = gameball.send_action(action_request)


# Example 3
import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

action_request = gameball.actionObject(player_unique_id = "151515")
action_request.add_player_attribute("displayName", "Python_v2")
action_request.add_player_attribute("name","Mohamad")
action_request.add_event("place_order", {"total_price":1500})
action_request.add_event("view_product_page")
action_request.add_points_transaction(transaction_id= "810008204529", reward_amount=20, hold_reference="1f306d48-706d-b3718ae7e5e2")
action_response = gameball.send_action(action_request)

Get Player Info Example

# Example 1
import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

player_info_response = gameball.get_player_info(player_unique_id= 17315)


# Example 2
import gameball
gameball.api_key = "gb_test_..."
gameball.transaction_key = "gb_test_..."

player_info_response = gameball.get_player_info(player_unique_id= 17315, language= gameball.Languages.Arabic)

Initialize Player Example

import gameball
gameball.api_key = "gb_test_..."

player_request = gameball.playerObject(" player123")
player_request.add_player_attribute("displayName", " Jon Snow")
player_request.add_player_attribute("email", "jon.snow@example.com")
player_request.add_player_attribute("dateOfBirth", "1980-09-19T00:00:00.000Z")
player_request.add_player_attribute("joinDate", "2019-09-19T21:06:29.158Z")
player_response = gameball.initialize_player(player_request)

Handling exceptions

Unsuccessful requests raise exceptions. The raised exception will reflect the sort of error that occurred with appropriate message and error code . Please refer to the Gameball API docs.

Contribution

---

The master branch of this repository contains the latest stable release of the SDK.

Contact

---

For usage questions\suggestions drop us an email at support[ at ]gameball.co. Please report any bugs as issues.