Skip to content
SignupKit is the official framework by UVA Advancement Communications to sign users up for email publications sent through our constituent management system. The included API, designed to be used in a ReSTful call, transmits data via a proxy to our public API.
PHP
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo
src
tests
.gitignore
README.md
composer.json
composer.lock

README.md

SignupKit

v 2.0

SignupKit is the official framework by UVA Advancement Communications to sign users up for email publications sent through our constituent management system. The included API, designed to be used in a ReSTful call, transmits data via a proxy to our public API.

For an example on how this can be used, check out our demo.

Features

  • Send user information securely to our API to sign users up for newsletters

How it works

To send data securely to our API, called SignupCore, the data will be sent via a proxy placed on your server called SignupKit. By default, this SignupKit proxy file is stored under ~/lib/api/ but can be stored anywhere as long as the file structure inside of ~/lib/api/ goes unmodified.

When you transmit an entry, the data will be sent via HTTPS to SignupCore as a JSON web token. The data you transmit will be encrypted using a shared secret assigned to your installation and decrypted by SignupCore. The below diagram is a representation of how the information gets transmitted from a user's browser, to SignupKit, and then to SignupCore.

Requirements

Please note that the full functionality of this code requires registration with Advancement Communications. They will supply your API key in a signupkit-config.php file that should be placed in the same directory as signupkit-config-sample.php.

Since APIs may be deprecated over time, we strongly recommend against changing the SignupKit Proxy files (~/lib/api/index.php and ~/lib/api/signupkit-object/sko.php). As features are added and modified, replacing these files will be necessary to communicate to the most current version of our API.

Notably, you are responsible for basic authentication to your proxy via ReCaptcha or a similar filtering tool. The SignupKit API will only return invalid email address, but cannot filter out against spam.

Installation

The easiest way to install SignupKit is using the dependency manager Composer. To do this, simply run the following command:

composer config repositories.uva-signup-kit vcs https://github.com/jordanleven/uva-signupkit && composer require uva/signup-kit

This command will add the GitHub repository to your composer.json file and install SignupKit, and all dependencies, to your vendor directory.

Getting Started

After receiving your credentials file, you can begin testing your service. Start by ensuring that the constant SIGNUP_CORE_SET_ENV_TO_STAGING in signupkit-config.php is set to true. This will send all of your entries to our staging environment. This will allow you to test sending entries, but without actually subscribing any emails. Now you're ready to begin building your application.

Parameters

These are the parameters you'll be sending to SignupKit that are, in turn, sent to SignupCore.

Post values

Parameter Type Description
first_name string The first name of the user you'd like to subscribe.
last_name string The last name of the user you'd like to subscribe.
email_address string The email address of the user you'd like to subscribe. This value will be validated via SignupCore, so it is not necessary to validate the value on the client end (although it is preferred to ensure the value is nonnull).
newsletter (optional) string The newsletter you'd like to sign the user up for. If no value is provided to SignupKit, it will assume a default newsletter that's defined in signupkit-config.php.

Return values

Your proxy file will always return the following parameters:

Parameter Type Description
success bool A true or false as to whether or not your call was successful. For these purposes, true will correspond to any HTTP response under 300.
status_code int The HTTP code associated with the status of your call. This code will also be sent in the response headers.
status_text string A return message to describe the status_code. These messages may or may not be relayed verbatim to users.
return_data Object If the status_code has additional values, they'll be shared here. This is particularly useful for debugging purposes.

Sending via AJAX

Transmit data via AJAX is easy! As an example, here's how you could set up your form:

HTML Example
The first three inputs are the most important since it's the core information that is used to subscribe a constituent. Although optional, the newsletter input is used to specify a specific newsletter to sign up for. The only reason why you'd need to use this is if you have multiple forms hitting your installation of SignupKit and you are attempting to subscribe a constituent to a newsletter that is different than SIGNUP_KIT_NEWSLETTER_DEFAULT. If you have a specific newsletter defined in SIGNUP_KIT_NEWSLETTER_OVERRIDE, passing this attribute has no effect: the value defined in defined specific newsletter defined will be used no matter what.

<form id="newsletter-form" class="form-inline">
<div class="form-group">
<input name="first_name" type="text" class="form-control" placeholder="First name" value="Johnny">
</div>
<div class="form-group">
<input name="last_name" type="text" class="form-control" placeholder="Last name" value="Appleseed">
</div>
<div class="form-group">
<input name="email_address" type="email" class="form-control" placeholder="Email" value="jappleseed@virginia.edu">
</div>
<div class="form-group">
<input name="newsletter" type="hidden" value="test_newsletter">
</div>
<button type="submit" class="btn btn-default">Sign up</button>
</form>

jQuery Example
Here, we are binding a submit event to the form newsletter-form and using preventDefault() to prevent the page from reloading. We use jQuery's .each() function to grab all values of the inputs. Since the name of each input is the same as the parameter it represents, we use the input name as the key for its value. This approach isn't required, however. You can name these fields whatever you want, as long as the correct parameter names are being using when sending the data to SignupKit.

Afterwards, we use jQuery's ajax method to send the data via an asynchronous HTTP request to our proxy file and add handling to the promises (done,fail, and always). Notably, the url parameter is pointed at your proxy file and not the SignupCore URL. This is so 1) your proxy can generate the JWT using your shared secret; and 2) so users of your site aren't directly communicating with our API.

If the call to the API is successfully received (that is, a response is returned without AJAX errors), we can handle the response based on the success parameter. Note that user errors (missing fields, incorrectly formatted email addresses) are not considered to be request failures and will be handled under the done promise. AJAX errors (incorrectly formatted error messages, timeouts, etc) will be handled under the fail promise.

The only error messages generated on your proxy file will be the 402 error (missing signupkit-config.php file). All other messages will be sent to the user indirectly from the SignupCpre API.

$(function(){
    $('#send-via-asynchronous-request')
    .submit(function(e){

        // We're handling the action ourselves, so prevent the page from refreshing
        e.preventDefault();

        // Declare the element's scope
        var this_element = $(this);

        // Create the array we'll use to send data
        var signupkit_data = {};

        $(this_element)
        .find('.form-group')
        .each(function(){

            // Get this group's element
            var group_element = $(this).children('input');

            // Get the group key
            var group_key = $(group_element).attr('name');

            // Get the group value
            var group_value = $(group_element).val();

            // Add the data to the array
            signupkit_data[group_key] = group_value;

        });

        $.ajax({
            url      : 'api/SubscribeToNewsletter',
            method   : 'POST',
            data     : signupkit_data,
            dataType : 'json',
        })
        .done(function(signupcore_response) {

            if (signupcore_response.success){

                $(this_element)
                .find(".alert")
                .remove()
                .end()
                .prepend('<div class="alert alert-success alert-temp" role="alert"><strong>Success!</strong> ' + signupcore_response.status_text + '</div>')
                .find('.form-group input')
                .val('');

            } 

            else {

                $(this_element)
                .find(".alert")
                .remove()
                .end()
                .prepend('<div class="alert alert-danger alert-temp" role="alert"><strong>Oops...</strong> ' + signupcore_response.status_text + '</div>');

            }
        })
        .fail(function(signupcore_response) {

            console.warn("Ajax error!");

            $(this_element)

            .find(".alert")
            .remove()
            .prepend('<div class="alert alert-danger alert-temp" role="alert"><strong>Oops...</strong> AJAX error.</div>');

            console.warn( signupcore_response );

        });

    });
});

Dependencies

SignupKit uses several dependencies that are included in the composer.json file. These dependencies include:

License

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

You can’t perform that action at this time.