Darkwaltz4
Former Developer
I built vBCredits II Deluxe to be easy to integrate, not just for myself, but for others. Integration must be done via code, so the first thing you should do is enable vBulletin debug mode and create your own product. This will turn on the full Action and Display editors. You might also want to check out the vBookie actionset for a good example of all of these being used.
Actions
What kinds of things could you earn or spend credits on in your addon? As the label implies, these things should be distinct things that users perform. Decide on a few, and we will start by creating a new action via the Action Manager.
Go ahead and look at how the other Actions are set up to help you put together your own. Be sure to expand the advanced options. Come up with a unique identifier for your Action and remember it for later. Read each attribute carefully and decide how your action behaves. Each of these properties must be supported in your API calls, but these settings determine the corresponding features available during Events.
You can add your own category options by adding a new phrase under your product in the vBCredits Administration Phrases with a variable name like: credits_category_[something]. It will show up in that dropdown then.
When you have saved the action, look in the credits_action table. Your product will need to REPLACE INTO the credits_action table that very row upon installation. The primary key is the actionid that you came up with. After adding all the rows you want in your installer, you will need to rebuild the caches for it to show up immediately:
Next, you need to find within your code or plugin where that Action actually happens, and insert this line of code:
In the pre hook, pass boolean true as the $refid. The API call will then return an ID which you need to hang onto. At this point the Transaction has not yet been committed, but it has been validated and will react as normal if for example a user does not have enough credits. Next in the post hooks, use this:
So just pass the ID returned from the API call to action() and the refid which you were unable to send there before. This will commit the Transaction and again, splitting into two API calls is not always necessary if you send the refid to begin with.
Note, if you are calling this somewhere that doesn't terminate in print_output() or vBulletin's ajax handler (such as outside of a vb plugin, custom script, etc.), you need to use this afterwards to actually commit the transaction:
That's it for Events, the core will take care of everything else, including stopping the Action with error messages as it applies. For recalculations, there is a credits_actions_rebuild hook for you to use. Mark your Actions that support this feature, as the ones that don't are still eligible for reprocessing automatically without your help, however they don't work for past Actions. There, you have the following to work with:
Currency Import Wizard
Want to define a currency that will be detected automatically? Just use the credits_currency_wizard and add an entry to the $currencies array, with your own array that contains the following keys that you should recognize from the credits_currency table:
Displays explained soon.
Let me know if you have any questions, comments, or suggestions!
Actions
What kinds of things could you earn or spend credits on in your addon? As the label implies, these things should be distinct things that users perform. Decide on a few, and we will start by creating a new action via the Action Manager.
Go ahead and look at how the other Actions are set up to help you put together your own. Be sure to expand the advanced options. Come up with a unique identifier for your Action and remember it for later. Read each attribute carefully and decide how your action behaves. Each of these properties must be supported in your API calls, but these settings determine the corresponding features available during Events.
You can add your own category options by adding a new phrase under your product in the vBCredits Administration Phrases with a variable name like: credits_category_[something]. It will show up in that dropdown then.
When you have saved the action, look in the credits_action table. Your product will need to REPLACE INTO the credits_action table that very row upon installation. The primary key is the actionid that you came up with. After adding all the rows you want in your installer, you will need to rebuild the caches for it to show up immediately:
PHP:
vbcredits_cache();
Next, you need to find within your code or plugin where that Action actually happens, and insert this line of code:
PHP:
VBCREDITS::action($actionid, $userid, $refid = null, $negate = false, $extra = array());
*Now, sometimes hooks might be in places that are not entirely ideal, such as when other validation of an Action occurs AFTER the API call, and so users might unfairly earn or spend credits for an Action that ultimately fails. Furthermore, checking if a user has enough credits to spend on an Action if an Event is so configured is an important part of verification itself. Sometimes you won't even know the refid of an Action until after it has been validated and saved to a database, but still a part of the transaction record. Datamanagers are notorious for this, but they generally have a pre and post hook which you can use the following to overcome:$actionid - string, the actionid of the Action you are triggering.
$userid - int, the userid of the user who is performing the Action. Doesn't always have to be the currently logged in user, but still must be passed if it is.
$refid - mixed, this goes along with the reference URL of the Action, if you set one. If there isn't one and you left that property blank in the action manager, then pass null. Passing boolean true is explained later*
$negate - bool, true if the negation part of the Event should be used. If you set this in the Action properties, then you should have two API calls in the appropriate places; one for the Action regularly happening, and the other for when it is negated, and passed with true here.
$extra - array with the following keys, which should be included as they apply:
'message' - string, any text which will go into the Transaction logs, such as a high score or a note with a donation, etc.
'multiplier' - numeric, the value of the multiplier entity if you set one for your Action. For Size multipliers, pass the user-supplied text and it will automatically be counted according to user settings like ignoring bbcode. For Currency multipliers, pass the properly signed amount.
'timestamp' - unix timestamp int, useful for "catching up" Actions. If not included then TIMENOW will be used.
'currencyid' - unsinged int, generally used for user-selected Currency multiplier Actions, such as when donating or transferring a specific currency for a specific amount.
'forumid' - unsigned int, the forumid that applies to this Action, if the global property was not set.
'userinfo' - array, full user info array for the user triggering the Action, including permissions. Useful for speeding up transactions not for the current user. If not included then $vbulletin->userinfo will be used.
'ownerid' - unsigned int, userid who owns the parent entity of the current entity according to your Action settings. For example, the parent entity of a post is a thread, and a user owns that, but might not own the thread, and events can be built taking that into effect.
In the pre hook, pass boolean true as the $refid. The API call will then return an ID which you need to hang onto. At this point the Transaction has not yet been committed, but it has been validated and will react as normal if for example a user does not have enough credits. Next in the post hooks, use this:
PHP:
VBCREDITS::apply($apiid, $refid);
Note, if you are calling this somewhere that doesn't terminate in print_output() or vBulletin's ajax handler (such as outside of a vb plugin, custom script, etc.), you need to use this afterwards to actually commit the transaction:
PHP:
VBCREDITS::shutdown();
Of course, you have the rest of the environment available. You should run any queries for that Action and user during that range, and issue new API calls as detailed above, filling in the usual information. It is highly recommended that you include the timestamp field according to the time that you determine a recalculated action happened, so that the Transaction log looks like everything happened at the correct time in the correct order. Generally, any Actions that originally required two API calls can be merged into just the first one.$actionid - test for the values you are handling in a switch statement or similar.
$user - the array of the current user being processed.
$vbulletin->GPC['start_date'], $vbulletin->GPC['end_date'] - range of time chosen by the user.
Currency Import Wizard
Want to define a currency that will be detected automatically? Just use the credits_currency_wizard and add an entry to the $currencies array, with your own array that contains the following keys that you should recognize from the credits_currency table:
vBCredits II Deluxe will take care of the rest, from import to transfer!'title' - string, the default of what th currency is called, usually from a setting or phrase
'productid' - string, the product that creates the currency
'minversion' - string, optional version of the product where the currency first appears
'maxversion' - string, optional version of the product where the currency is no longer available
'table' - string, the table that the currency column is found
'useprefix' - bool as int, if the table should have the vbulletin prefix included
'userid' - bool as int, if the table joins with the userid instead of the username
'usercol' - string, the column on the table which joins on the userid or username
'column' - string, the column which contains the actual currency values for each user
Displays explained soon.
Let me know if you have any questions, comments, or suggestions!
Last edited: