1. Customize
  2. Tutorials
  3. Creating a custom event

Creating a custom event

GamiPress events are the conditional action that an user need to perform in order to complete anything inside GamiPress.

The events system is based on listeners and triggers (as any events system). So to add your own events you need just to follow the next steps:

1 – Register the event.
2 – Place a listener to “listen” the users actions.
3 – Trigger the event to let GamiPress know that user has perform this action.

Registering the event

The first step is register a custom event to become a selectable item on the available events dropdown displayed on the requirements UI.

For this, you will need to hook to the gamipress_activity_triggers filter as the following code shows:

function my_prefix_custom_activity_triggers( $triggers ) {

    // The array key will be the group label
    $triggers['My Custom Events'] = array(
        // Every event of this group is formed with:
        // 'event_that_will_be_triggered' => 'Event Label'
        'my_prefix_custom_event' => __( 'Custom event label', 'gamipress' ),

        // Also, you can add as many events as you want
        // 'my_prefix_another_custom_event' => __( 'Another custom event label', 'gamipress' ),
        // 'my_prefix_super_custom_event' => __( 'Super custom event label', 'gamipress' ),
    );

    return $triggers;

}
add_filter( 'gamipress_activity_triggers', 'my_prefix_custom_activity_triggers' );

GamiPress automatically will use the event label for auto-generate the requirement label when is empty, there are a few examples with a label like “Comment on a post”:

– Achievement step example: Comment on a post 2 times
– Points award example: 10 points for comment on a post 5 times

Listening to the user action and let it know to GamiPress

Placing a listener to user actions is simply hook a WordPress (or plugin) action or filter that confirms that user has perform it.

To hook an action you just need to use the add_action() function and to hook a filter, the add_filter() function.

As last step you need to let it know to GamiPress, and the easiest way is through the gamipress_trigger_event() function.

Important: gamipress_trigger_event() requires at least the event and user_id to meet which user has perform the action.

function my_prefix_custom_listener( $args ) {

    // Call to the gamipress_trigger_event() function to let know GamiPress this event was happened
    // GamiPress will check if there is something to award automatically
    gamipress_trigger_event( array(
        // Mandatory data, the event triggered and the user ID to be awarded
        'event' => 'my_prefix_custom_event',
        'user_id' => get_current_user_id()

        // Also, you can add any extra parameters you want
        // They will be passed too on any hook inside the GamiPress awards engine
        // 'date' => date( 'Y-m-d H:i:s' ),
        // 'custom_param' => 'custom_value',
    ) );

}
// The listener should be hooked to the desired action through the WordPress function add_action()
add_action( 'action_we_want_to_hook', 'my_prefix_custom_listener' );

Check the official WordPress Hooks reference to meet more about actions and filers.

Full template to register events

The following snippet is the full template that you can use to register your own events to being used through the requirements UI.

function my_prefix_custom_activity_triggers( $triggers ) {

    // The array key will be the group label
    $triggers['My Custom Events'] = array(
        // Every event of this group is formed with:
        // 'event_that_will_be_triggered' => 'Event Label'
        'my_prefix_custom_event' => __( 'Custom event label', 'gamipress' ),

        // Also, you can add as many events as you want
        // 'my_prefix_another_custom_event' => __( 'Another custom event label', 'gamipress' ),
        // 'my_prefix_super_custom_event' => __( 'Super custom event label', 'gamipress' ),
    );

    return $triggers;

}
add_filter( 'gamipress_activity_triggers', 'my_prefix_custom_activity_triggers' );

function my_prefix_custom_listener( $args ) {

    // Call to the gamipress_trigger_event() function to let know GamiPress this event was happened
    // GamiPress will check if there is something to award automatically
    gamipress_trigger_event( array(
        // Mandatory data, the event triggered and the user ID to be awarded
        'event' => 'my_prefix_custom_event',
        'user_id' => get_current_user_id()

        // Also, you can add any extra parameters you want
        // They will be passed too on any hook inside the GamiPress awards engine
        // 'date' => date( 'Y-m-d H:i:s' ),
        // 'custom_param' => 'custom_value',
    ) );

}
// The listener should be hooked to the desired action through the WordPress function add_action()
add_action( 'action_we_want_to_hook', 'my_prefix_custom_listener' );

A real world example

Let’s to see a real world example based on the “purchase a product” event provided on GamiPress – WooCommerce Integration.

function my_prefix_custom_activity_triggers_for_purchase_a_product( $triggers ) {

    $triggers['My Custom Purchase Events'] = array(
        // Register the event my_prefix_custom_purchase_event
        'my_prefix_custom_purchase_event' => __( 'Purchase a product', 'gamipress' ),
    );

    // GamiPress automatically will use the event label for auto-generate the requirement label
    // Some examples with "Purchase a product" label:
    // Step example: Purchase a product 2 times
    // Points award example: 10 points for purchase a product 5 times

    return $triggers;

}
add_filter( 'gamipress_activity_triggers', 'my_prefix_custom_activity_triggers_for_purchase_a_product' );

function my_prefix_custom_listener_for_purchase_a_product( $order_id ) {

    $order = wc_get_order( $order_id );

    foreach ( $order->get_items() as $item ) {

        // Call to gamipress_trigger_event() on each product purchased
        gamipress_trigger_event( array(
            'event' => 'my_prefix_custom_purchase_event', // Set our custom purchase event
            'user_id' => $order->user_id, // User that will be awarded is the one who made the order

            // Add any extra parameters you want
            // In this example we passed the product ID and the order object itself
            'product_id' => $item->get_product_id(),
            'order' => $order,
        ) );

    }
    
}
// The safe way to check if an user has perform a purchase is when an order payment is set to completed
// So let's hook the 'woocommerce_payment_complete' action
add_action( 'woocommerce_payment_complete', 'my_prefix_custom_listener_for_purchase_a_product' );

More examples

Almost every GamiPress add-on provides new events related to custom functionalities, like content sharing events provided by Social Share add-on, or events related to specific plugin actions, like form submissions provided by the Ninja Forms Integration add-on.

Some of the events will use GamiPress default functionalities and other will add new fields to the requirements UI and extra checks to the awards engine, so feel free to check their code to develop complex events.

In addition, you can check the Creating a custom event related to a specific post tutorial to meet how to register events related to a specific post.

Was this article helpful to you? Yes 2 No

How can we help?