Backend Developer Docs

Nextend Social Login Documentation

Warning:

You need to have a developer’s knowledge to be able to use the actions and filters below. We are not able to provide support for custom coding!

Actions

nsl-add-providers

This action helps you adding new providers to the plugin.

nsl-providers-loaded

This action runs after every provider has been loaded and ordered correctly.
NextendSocialLogin::$providers contains all available providers.
NextendSocialLogin::$enabledProviders contains only the enabled providers.

Connect Flow actions/filters

{{provider-id}}_login_action_before

This action run first after the user clicked the social login button. It has only one parameter, the current provider. It extends from the NextendSocialProvider class.

{{provider-id}}_login_redirect_url

A filter to override the login redirect url. It has two parameters:

  • Fixed redirect URL, if set
  • current provider

It returns the new redirect URL.
Example:
add_filter('facebook_login_redirect_url', function($redirectUrl, $provider){ return $redirectUrl;}, 10, 2);

{{provider-id}}_register_redirect_url

It’s the same as the {{provider-id}}_login_redirect_url. It has the same two parameters, but it happens upon registration:

  • Fixed redirect URL, if set
  • current provider

nsl_register_new_user

This happens when a new user is registered with any of the providers. Parameteres:

  • $user_id
  • provider instance

nsl_{{provider-id}}_register_new_user

This action runs when the user registers with the given provider. Parameters:

  • $user_id
  • provider instance

nsl_{{provider-id}}_auto_link_allowed

This filter can prevent linking the user accounts automatically for a user when it returns false.
Parameters:

  • $isAutoLinkAllowed
  • current provider instance
  • $user_id

nsl_{{provider-id}}_is_login_allowed

This filter can prevent the login for the user when it returns false.
Parameters:

  • $isAutoLoginAllowed
  • current provider instance
  • $user_id

nsl_login

This action runs when a user logs in with any of the providers.
Parameters:

  • $user_id
  • provider instance

nsl_{{provider-id}}_login

This action runs when a user logs in with the given provider.
Parameters:

  • $user_id
  • provider instance
  • access_token

nsl_pre_register_new_user

This action runs before the new user is registered.
Parameters:

  • NextendSocialUser class instance

nsl_is_register_allowed

This filter defines whether the user registration is allowed or not.
Parameters:

  • boolean
  • provider instance

Available since: 3.0.4

nsl_{{provider-id}}_link_user

This action runs when a user link the account to a given provider, registration with the given provider also triggers this hook.
Parameters:

  • $user_id
  • provider id

This action runs when a user unlinks a social media account from a certain provider.
Parameters:

  • $user_id
  • provider id
  • unlinked social media id

Available since: 3.0.28 / “unlinked social media id” parameter added in 3.1.6

nsl_registration_user_data

This filter can be used for overriding certain userdata before the registration or preventing the registration.
Parameters:

  • $userData – associative array – username and email
  • $provider – provider instance, that can be used to retrieve some data of current user.
  • $error – error object, that can be used for preventing the registration.

nsl_disabled_register_redirect_url

This filter can be used for overriding the URL where the user will be redirected, if the registration is disabled.
Parameters:

  • $redirectUrl – string – the url of the page

Available since: 3.0.25

nsl_disabled_register_error_message

This filter can be used for overriding the message that is displayed when the registration is disabled with Nextend Social Login.
Parameters:

  • $errorMessage – string – the error message
  • $provider – provider instance

Starting from version 3.0.28 passing “false” in the return value can be used for disabling the default error message!

Available since: 3.0.25

nsl_{{provider-id}}_auth_url_args

This filter can be used for overriding authorization URL arguments of each provider.
Parameters:

  • $args – associative array – contains the current authorization URL arguments.

Available since: 3.0.26

This filter can be used for overriding the User ID that the social account should be linked to.
Parameters:

  • $user_id – the ID of the WordPress account where the social account should be linked to
  • social user instance
  • current provider instance

Available since: 3.0.26

nsl_disabled_login_redirect_url

This filter can be used for overriding the URL where the user will be redirected, if the login is disabled.
Return value:

  • string – the URL where the user should be redirected

Available since: 3.0.27

nsl_disabled_login_error_message

This filter can be used for overriding the message that is displayed when the login is disabled with Nextend Social Login.
Return value:

  • string – the error message

Available since: 3.0.27

nsl_already_linked_error_message

This filter can be used for overriding the message that is displayed when a person tries to connect with a social media account, that’s email address is registered on the site and has another social media account from the same kind already linked.
Return value:

  • string – the error message

Available since: 3.0.30

nsl_bypass_cache_url

This filter can be used for adding custom GET parameters to the redirect URL, when the “Bypass cache on redirect” setting is enabled. By default the name of the parameter is “nsl_bypass_cache” and its value is a unique hash.
Parameters:

  • $url – string – the URL where the user should be redirected to

Return value:

  • string – the URL where the user should be redirected to ( To attempt bypassing the cache, at least one GET parameter should be added into the URL! )

Example:
add_filter('nsl_bypass_cache_url', function ($url) { return add_query_arg(array("abc" => "123"), $url); });

Available since: 3.1.4

nsl_connect_button_custom_attributes

You can use this filter to add custom attributes to the connect button.

Example:

add_filter('nsl_connect_button_custom_attributes', function ($attr, $provider) {
    $attr['attrbute'] = "value";
    return $attr;
}, 10, 2);

Available since: 3.1.5

nsl_register_roles

You can use this filter to override the role that the user should be registered with.
Parameters:

  • $roles – array – contains the role or roles that the user should be registered with
  • $provider – provider instance, that can be used to retrieve some data of current user.

Available since: 3.1.14

Using the trackerdata shortcode function

Nextend Social Login allows you to do custom actions when the user logs in using the login buttons. Add the trackerdata attribute to the shortcode:

[nextend_social_login trackerdata="my-tracker-data"]

Then you can write custom codes to change the user role based on the page where the user has registered or to save down extra information.

Example: using trackerdata to identify the page the user registered

For this you’ll need to use the shortcode with a custom trackerdata value. In this tutorial the registered_from value will be used

[nextend_social_login trackerdata="registered_from"]

Then you’ll need to set up cookies to save down the URL of the current page:

<script type="text/javascript">
    function setCookie(name,value,days) {
  var expires = "";
  if (days) {
    var date = new Date();
    date.setTime(date.getTime() + (days*24*60*60*1000));
    expires = "; expires=" + date.toUTCString();
  }
  document.cookie = name + "=" + (value || "") + expires + "; path=/";
}
setCookie('registered_from', '<?php global $wp; echo home_url( $wp->request ) ?>', 7);</script>

And you’ll also need a PHP code to work with the cookie. The nsl_register_new_user action runs just before the registration process is finished, so you can use it to get the tracker data and add a new user meta.

<?php add_action('nsl_register_new_user', function ($user_id) {
    if (NextendSocialLogin::getTrackerData() == "registered_from") {
        $user = new WP_User($user_id);
        add_user_meta($user->ID, 'registered_from', $_COOKIE['registered_from']);
    }
});?>

You could create a custom plugin to add these codes. You can find a working sample below:

<?php
/*
Plugin Name: NSL trackerdata
Description: Track the page where users logged in using Nextend Social Login
Version: 1
 */

add_action('wp_head', 'set_custom_cookie');
function set_custom_cookie(){
    ?>
    <script type="text/javascript">
    function setCookie(name,value,days) {
  var expires = "";
  if (days) {
    var date = new Date();
    date.setTime(date.getTime() + (days*24*60*60*1000));
    expires = "; expires=" + date.toUTCString();
  }
  document.cookie = name + "=" + (value || "") + expires + "; path=/";
}
setCookie('registered_from', '<?php global $wp; echo home_url( $wp->request ) ?>', 7);</script>
    <?php
};

add_action('nsl_register_new_user', function ($user_id) {
    if (NextendSocialLogin::getTrackerData() == "registered_from") {
        $user = new WP_User($user_id);
        add_user_meta($user->ID, 'registered_from', $_COOKIE['registered_from']);
    }
});

Example: using trackerdata to override the role that the user gets registered with

Suppose you have a marketplace, where you allow the registration with 2 different roles: vendor and customer. For each role you have different registration forms.
Normally, the registration with social login won’t consider the roles of the forms, as by default Nextend Social Login registers the users with the WordPress default role set at WordPress > Settings > General > New user default role. To make the social login register new accounts with:

  • the customer role in the customer registration form
  • the vendor role in the vendor registration form

you need the following setup:

  1. to display the social buttons in the customer form, publish them using the shortcode, e.g.: [nextend_social_login]
  2. set the WordPress default role to “customer”, this way the registration with social login will automatically assign the customer role to the new account
  3. to display the social buttons in the vendor form and to be able to identify these social buttons for the vendor registration, publish them using the shortcode with the trackerdata parameter, e.g.: [nextend_social_login trackerdata="vendor"]
  4. finally to register the users with the vendor role in the vendor form, use the nsl_register_roles filter to override the default role, whenever the tracker data matches the one you set for the vendor specific shortcode. E.g.:

Validate Username

You can add custom validation to the entered username using the nsl_validate_username filter.

Example:

add_filter('nsl_validate_username', function ($isValid, $username, $errors) {
    if (strlen($username) < 6) { $errors->add('invalid_username', '' . __('ERROR') . ':' . __('Sorry, username must contain at least 6 characters.'));
        $isValid = false;
    }
    return $isValid;
}, 10, 3);

Available since: 3.0.7

Override the userdata (username/email) before registration

You can override the username or the email in the $userData using the nsl_registration_user_data filter.

Example:

add_filter('nsl_registration_user_data', function($userData, $provider){
    $userData['username']=$provider->getAuthUserData('first_name').'-'.$provider->getAuthUserData('last_name');
            
    return $userData;
},10,2);

Available since: 3.0.15

Prevent registration with certain email domain

You can either allow or prevent registration with certain email domains using the nsl_registration_user_data filter.

Example – disable registration with the gmail.com email domain:

add_filter('nsl_registration_user_data', function ($user_data, $provider, $errors) {
    /**
     * List of banned domains. Multiple domains can be separated with commas e.g.: "gmail.com","yahoo.com"
     */
    $banned_domains = array("gmail.com");
    if (isset($user_data['email']) && !empty($user_data['email']) && is_email($user_data['email'])) {
        $email_parts = explode('@', $user_data['email']);
        if (in_array($email_parts[1], $banned_domains )) {
            /**
            * The error message.
            */
            $errors->add('invalid_email', '' . __('ERROR') . ': ' . __('Sorry, registration with this email domain is not allowed!'));
            return $user_data;
        }
    } else {
        $errors->add('invalid_email', '' . __('ERROR') . ': ' . __('Sorry, email is missing or invalid!'));
    }

    return $user_data;
}, 10, 3);

Available since: 3.0.20

Asking custom fields before the registration

You can use Nextend Social Login to ask custom information form the users before the registration process is finished and you can also validate this data.

In the example below you can see how to ask the favorite color of the person who registers.

Redirect user on login depending on its role

By combining the ‘nsl_login’ action and the ‘{{provider-id}}_login_redirect_url’ filter, you can control where the user with a specific role should land.

In this example, you can see a basic code snippet which redirects the users with the “subscriber” role to a custom link.

Exclude URL from Fixed redirect url – for Login/Register setting

In this example, you can see a basic code snippet which will prevent the Fixed redirect url – for Login/Register setting from redirecting to the specified URL, if the Google button is pressed on the ‘https://example.com/checkout’ page:

Display simple statistics in the Dashboard page

The code snippet below can display a simple statistics on the Dashboard page ( /wp-admin/index.php ) showing the number of connections per provider and the total number of connections across all enabled providers.

( Thank you Vlado for submitting this code snippet! )

Hide the avatars in the Media Library – List view

The code snippet below can hide the avatars in the List view of the Media Library, if the ‘Display avatars in “All media items”‘ setting is set to “Disabled”.