Formularios

Una excelente forma de hacer crecer nuestra base de contactos es tener un formulario donde los usuarios puedan suscribirse ingresando sus datos. A través del API de Perfit podemos crear estos formularios de Opt-In muy fácilmente y mostrarlos pegando un pequeño código en nuestro sitio web.

Lo mejor de todo es que podemos crear todos los que querramos: uno para ofrecer una suscripción a nuestro newsletter, otro para sumar a nuestros fans de Facebook, otro para que nuestros visitantes puedan sumarse a un seminario o evento, etc. Cada uno puede pedir diferentes datos y estar asociado a una lista diferente, por lo que podremos organizar nuestros nuevos contactos de forma muy sencilla.

A continuación veremos cómo lucen estos formularios, cómo podemos crearlos y administrarlos a través del API.

Proceso de suscripción

Para que podamos partir de una base común, veamos cómo luce un formulario típico una vez implementado en nuestro sitio web.

formulario

Como ven, es un formulario de suscripción a un newsletter que solicita el nombre y el email del usuario. Una vez que el usuario lo completa y presiona "Suscribirme", recibe un email en su cuenta de correo con un link para confirmar la suscripción.

email

A esto se denomina "suscripción en dos pasos" o "doble Opt-In". Al tener que confirmar por medio de un link único generado para esa suscripción en particular, esta técnica previene suscripciones indeseadas de bots que puedan completar el formulario miles de veces con direcciones de correo inexistentes.

Una vez que el usuario hace click en el link de confirmación, es dirigido a una página de agradecimiento y el contacto se agrega efectivamente en nuestra base.

thanks

La información del nuevo usuario sólo será visible luego de confirmar la suscripción.

A través del API de Perfit podemos personalizar todos estos elementos: los detalles y campos del formulario inicial, el texto del email de confirmación, la URL de la página de agradacimiento, etc.

A continuación, veamos la representación del formulario en el API.

Detalle del formulario

Enseguida veremos cómo crear un formulario, pero primero veamos cómo queda representado una vez creado. El objeto JSON que define el formulario que tomamos como ejemplo sería el siguiente:

{
    "id": 1,
    "pubId": "QFqy3plS",
    "created": "2015-01-01 10:20:00",
    "name": "Formulario Home",
    "description": "",
    "lists": [
        1,
        2
    ],
    "form": {
        "title": "Suscribite a nuestro Newsletter",
        "text": "Recibí nuestras novedades todas las semanas.",
        "buttonText": "Suscribirme",
        "footer": "",
        "redirect": "http://example.com/thanks",
        "fields": [
            {
                "id": 1,
                "displayName": "Nombre",
                "format": "TEXT",
                "required": false
            },
            {
                "id": 3,
                "displayName": "Email",
                "format": "EMAIL",
                "required": true
            }
        ],
        "interests": [
            {
                "id": 5,
                "displayName": "Newsletters",
                "selected": true
            },
            {
                "id": 2,
                "displayName": "Ofertas",
                "selected": true
            }
        ]
    },
    "confirmation": {
        "fromName": "Info",
        "fromAddress": "info@example.com",
        "subject": "Confirmá tu suscripción",
        "title": "Bienvenido a nuestra comunidad",
        "header": "Gracias por suscribirte a nuestro newsletter...",
        "linkText": "Confirmar suscripción",
        "footer": "",
        "redirect": "http://example.com/OK"
    }
}

Todos esos campos son editables: podemos hacer un formulario a la medida de nuestras necesidades. Veamos a continuación cada uno de las propiedades del formulario, que serán los parámetros que reciban las llamadas POST para crearlo y PUT para modificarlo.

Campos generales

id

ID del Opt-In. Esta propiedad es de sólo lectura.

pubId

ID público del Opt-In. Es el que se utilizará para implementar el formulario en el sitio de acceso público. Se asigna automáticamente y es de sólo lectura.

name

Nombre del Opt-In.

description

Descripción del Opt-In, detalle o comentarios.

created

Fecha de creación. Esta propiedad es de sólo lectura.

lists

Array de IDs de las listas a las que seran asociados los contactos que completen el formulario y confirmen la suscripción.

{
    "id": 1,
    "created": "2015-01-01 10:20:00",
    "name": "Formulario Home",
    "description": "Formulario del sitio web",
    "lists": [
        1,
        2
    ]
}

Campos del formulario HTML

Textos

En este apartado se definen todos los textos del formulario: su encabezado, el texto del botón, etc.

title

Título del formulario HTML. Por ejemplo, "Suscribite a nuestro newsletter".

text

Texto del cuerpo del formulario HTML. Por ejemplo, "Recibí nuestras novedades todas las semanas".

buttonText

Texto del botón del formulario HTML. Por ejemplo, "Suscribirme".

footer

Pie del formulario HTML. Por ejemplo, "Mantendremos tu email privado".

redirect

URL a donde redirigir luego de enviar el formulario. Recomendamos que sea una página de tu sitio que avise al usuario chequear su casilla. Si no se indica ninguna, se utiliza una página genérica.

{
    "form": {
        "title": "Suscribite a nuestro Newsletter",
        "text": "Recibí nuestras novedades todas las semanas.",
        "buttonText": "Suscribirme",
        "footer": "",
        "redirect": "http://example.com/thanks",
    }
}

Campos

Dentro de form se define fields, un array con todos los campos a mostrar en el formulario HTML. Por defecto el campo email debe estar siempre y ser obligatorio. Si no esta se agrega.

id

ID del campo. Puede ser un campo personalizado. Por ejemplo, si tenemos un campo personalizado llamado "DNI" y queremos utilizarlo, debemos especificar su ID numérico (que será siempre igual o mayor a 10).

displayName

Etiqueta del campo. Puede coincidir o no con el nombre del campo. Por ejemplo, si tenemos el campo "DNI" podemos definir su etiqueta como "Número de documento".

format

Formato del campo (TEXT, INT o DATE). Esta propiedad depende del campo utilizado y es de sólo lectura, pero útil a la hora de renderizar el formulario HTML.

required

Indica true si el campo es obligatorio. En tal caso, el campo incluirá la propiedad required. Por ende, los navegadores modernos (IE10+, Firefox, Chrome) evitarán que el formulario sea enviado si este campo no está completo.

{
    "form": {
        "fields": [
            {
                "id": 1,
                "displayName": "Nombre",
                "format": "TEXT",
                "required": false
            },
            {
                "id": 3,
                "displayName": "Email",
                "format": "EMAIL",
                "required": true
            }
        ]
    }
}

Intereses

Opcionalmente, podemos mostrar en nuestro formulario un listado de intereses a los que el usuario puede elegir asociarse. Esto nos permitirá luego enviar campañas específicas según los intereses que hayan marcado. Por supuesto, podemos editar manualmente cada contacto y asignarle los intereses que querramos, pero dejar esa opción en manos del suscriptor es una gran ventaja ya que sólo recibe aquello que le interesa y así aumentan las posibilidades de conversión.

Para mostrar el listado de intereses, debemos incluir dentro de form un objeto interests que contenga un array de elementos, uno por cada interés disponible, con los siguientes datos:

id

ID del interés.

displayName

Etiqueta del checkbox que representa al interés. Puede ser diferente al nombre del interés en cuestión. Por ejemplo, si el interés se llama "Ofertas", su etiqueta puede ser "Quiero recibir ofertas y promociones".

selected

Indica si el checkbox aparece chequeado por defecto. El usuario puede desmarcarlo, si así lo desea.

{
    "form" : {
        "interests": [
            {
                "id": 5,
                "displayName": "Newsletters",
                "selected": true
            },
            {
                "id": 2,
                "displayName": "Ofertas",
                "selected": true
            }
        ]
    }
}

Textos del email de confirmación

fromName

Nombre del remitente.

fromAddress

Email del remitente.

subject

Asunto del email.

title

Título del email. Aparecerá en el cuerpo del mail como un tag H1.

header

Texto del email. Aparecerá en el cuerpo del mail como un tag P.

linkText

Enlace de confirmación del email. Aparecerá en el cuerpo del mail como un tag A.

footer

Texto del pie del email. Aparecerá en el cuerpo del mail como un tag P.

redirect

URL adonde el usuario será redirigido luego de hacer click en el enlace de confirmación. Si no se indica ninguna, se utiliza una página genérica.

Agregar un formulario

Bien, ahora que conocemos todos las propiedades de un formulario Opt-In, estamos listos para crear uno. Excepto id, pubId y created, todas los otros valores son editables: pueden ser enviados como parámetros en las llamadas POST y PUT. Siempre deben respetar la jerarquía establecida en el objeto base.

Para comenzar, demos de alta un formulario. Debemos enviar un POST a optins con los parámetros que querramos personalizar:

$form = file_get_contents(
    'https://api.myperfit.com/v2/micuenta/optins',
    false,
    stream_context_create(['http'=> [
        'method'=>'POST',
        'header' => "Content-Type: application/x-www-form-urlencoded\r\n".
                    'X-Auth-Token: Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s',
        'content' => http_build_query([
            'name' => 'Seminario',
            'description' => 'Formulario de suscripción al seminario de Marzo',
            'lists' => [
                1,
                2
            ],
            'form' => [
                'title' => 'Suscribite a nuestro Newsletter',
                'text' => 'Recibí nuestras novedades todas las semanas.',
                'buttonText' => 'Suscribirme',
                'footer' => '',
                'redirect' => 'http://example.com/thanks',
                'fields' => [
                    [
                        'id' => 1,
                        'displayName' => 'Nombre',
                        'format' => 'TEXT',
                        'required' => false
                    ],
                    [
                        'id' => 2,
                        'displayName' => 'Apellido',
                        'format' => 'TEXT',
                        'required' => false
                    ],
                    [
                        'id' => 3,
                        'displayName' => 'Email',
                        'format' => 'EMAIL',
                        'required' => true
                    ],
                    [
                        'id' => 11,
                        'displayName' => 'Edad',
                        'format' => 'INT',
                        'required' => false
                    ]
                ],
                'interests' => [
                    [
                        'id' => 6,
                        'displayName' => 'Quiero recibir el newsletter mensual',
                        'selected' => true
                    ]
                ]
            ],
            'confirmation' => [
                'fromName' => 'Info',
                'fromAddress' => 'info@example.com',
                'subject' => 'Confirmá tu suscripción',
                'title' => 'Bienvenido a nuestra comunidad',
                'header' => 'Gracias por suscribirte a nuestro newsletter...',
                'linkText' => 'Confirmar suscripción',
                'footer' => '',
                'redirect' => 'http://example.com/OK'
            ]
        ])
    ]])
);
$.ajax({
    type: 'POST',
    url: 'https://api.myperfit.com/v2/micuenta/optins',
    headers: {X-Auth-Token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'},
    data: {
        name: 'Seminario',
        description: 'Formulario de suscripción al seminario de Marzo',
        lists: [
            1,
            2
        ],
        form: {
            title: 'Suscribite a nuestro Newsletter',
            text: 'Recibí nuestras novedades todas las semanas.',
            buttonText: 'Suscribirme',
            footer: '',
            redirect: 'http://example.com/thanks',
            fields: {
                {
                    id: 1,
                    displayName: 'Nombre',
                    format: 'TEXT',
                    required: false
                },
                {
                    id: 2,
                    displayName: 'Apellido',
                    format: 'TEXT',
                    required: false
                },
                {
                    id: 3,
                    displayName: 'Email',
                    format: 'EMAIL',
                    required: true
                },
                {
                    id: 11,
                    displayName: 'Edad',
                    format: 'INT',
                    required: false
                }
            },
            interests: {
                {
                    id: 6,
                    displayName: 'Quiero recibir el newsletter mensual',
                    selected: true
                }
            }
        },
        confirmation: {
            fromName: 'Info',
            fromAddress: 'info@example.com',
            subject: 'Confirmá tu suscripción',
            title: 'Bienvenido a nuestra comunidad',
            header: 'Gracias por suscribirte a nuestro newsletter...',
            linkText: 'Confirmar suscripción',
            footer: '',
            redirect: 'http://example.com/OK'
        }
    },
    success: function (response) {
        var data = response.data;
    }
});

Listar formularios

Para obtener un listado de todos los formularios de nuestro sistema, debemos hacer un pedido GET a optins. Cada uno de los registros va a contener sólo las propiedades principales que vimos previamente.

$forms = file_get_contents(
    'https://api.myperfit.com/v2/micuenta/optins',
    false,
    stream_context_create(['http'=> [
        'method'=>'GET',
        'header' => "X-Auth-Token: $access_token"
    ]])
);
$.ajax({
    type: 'GET',
    url: 'https://api.myperfit.com/v2/micuenta/optins',
    data: {
        limit: 100,
        token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'
    },
    success: function (response) {
        var data = response.data;
    }
});

Obtendremos:

{
    "href": "/micuenta/optins",
    "success": true,
    "paging": {
        "offset": 0,
        "limit": 20,
        "results": 1,
        "total": 1
    },
    "sort": {
        "sortBy": "name",
        "sortDir": "asc"
    },
    "data": [
        {
            "id": 1,
            "pubId": "QFqy3plS",
            "created": "2015-01-01 10:20:00",
            "name": "Formulario Home",
            "description": "",
            "lists": [
                1,
                2
            ],
        }
    ]
}

Modificar un formulario

Para modificar un formulario, debemos hacer un PUT a optins seguido del ID de la lista especificando sus nuevas propiedades.

Debemos tener en cuenta que al enviar un nuevo array de lists, form.fields o form.interests, los valores anteriores serán reemplazados completamente por los valores nuevos. Por ende, si nuestro formulario tenía varios campos (nombre, apellido, email, edad) y en el PUT enviamos solamente uno (email), los campos restantes (nombre, apellido, edad) no serán mostrados desde ese momento en adelante.

Veamos un ejemplo:

$form = file_get_contents(
    'https://api.myperfit.com/v2/micuenta/optins/31',
    false,
    stream_context_create(['http'=> [
        'method'=>'PUT',
        'header' => "Content-Type: application/x-www-form-urlencoded\r\n".
                    'X-Auth-Token: Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s',
        'content' => http_build_query([
            'description' => 'Formulario para el webinar de Marzo',
            'lists' => [
                14,
                52
            ],
            'form' => [
                'fields' => [
                    [
                        'id' => 3,
                        'displayName' => 'Email',
                        'format' => 'EMAIL',
                        'required' => true
                    ]
                ],
            ]
        ])
    ]])
);
$.ajax({
    type: 'PUT',
    url: 'https://api.myperfit.com/v2/micuenta/contacts',
    headers: {X-Auth-Token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'},
    data: {
        description: 'Formulario para el webinar de Marzo',
        lists: {
            14,
            52
        },
        form: {
            fields: {
                {
                    id': 3,
                    displayName: 'Email',
                    format: 'EMAIL',
                    required': true
                }
            },
        }
    },
    success: function (response) {
        var data = response.data;
    }
});

Eliminar un formulario

Para eliminar un formulario, debemos hacer un DELETE a la misma URL.

$form = file_get_contents(
    'https://api.myperfit.com/v2/micuenta/optins/31',
    false,
    stream_context_create(['http'=> [
        'method'=>'DELETE',
        'header' => "Content-Type: application/x-www-form-urlencoded\r\n".
                    'X-Auth-Token: Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'
    ]])
);
$.ajax({
    type: 'DELETE',
    url: 'https://api.myperfit.com/v2/micuenta/optins/31',
    headers: {X-Auth-Token: 'Shjg23Asd4Sdg8fd23F4eg8rF83kgd2s'},
    success: function (response) {
        var data = response.data;
    }
});

¡Cuidado! Los formularios eliminados que hayamos embebido en nuestro sitio web o redes sociales darán error y no podrán ser renderizados. Debemos estar seguros de quitarl su código de todos los lugares donde lo hayamos incluído antes de eliminarlo mediante esta llamada.

Embeber un formulario

Una vez que tenemos nuestro formulario creado, podemos comenzar a utilizarlo. Mostrarlo en nuestro sitio es muy sencillo, solo necesitamos pegar un código HTML como este:

<!-- Optin-In Code Start -->
<div id="optin-QFqy3pS"></div>
<link rel="stylesheet" type="text/css" href="https://optin.myperfit.com/res/css/micuenta/QFqy3pS.css">
<script type="text/javascript" src="https://optin.myperfit.com/res/js/micuenta/QFqy3pS.js"></script>
<!-- Optin-In Code End -->

Como pueden ver, este código HTML inserta tres tags:

  • Un DIV que contendrá el formulario HTML.
  • Un CSS que servirá para darle estilo a dicho formulario.
  • Y un script que se encargará de renderizarlo una vez que la página cargue.

La URL de los recursos CSS y Javascript es deducible: inicia con la URL de los recursos del optin, seguido por el nombre de la cuenta y el ID público del formulario, con una extensión .css o .js según corresponda.

El script contiene toda la informacion del formulario: los campos, los intereses, el texto de los botones y encabezados, etc. Por eso puede renderizar el formulario a la perfección en el DIV que situamos en un principio. El resultado final es un HTML como el siguiente:

<div id="optin-QFqy3pS">
    <form method="POST" action="https://pubapi.myperfit.com/v2/optin/micuenta/QFqy3pS" class="p-optin">
        <div class="p-header">Recibi nuestro Newsletter</div>
        <div class="p-body">
            <p>Este es el texto.</p>
            <input type="hidden" value="http://example.com/pending" name="redirect">
            <div class="p-field">
                <label><span>Nombre</span></label>
                <input type="TEXT" placeholder="Nombre" name="fields[1]">
            </div>
            <div class="p-field">
                <label><span>Email</span></label>
                <input type="EMAIL" required="" placeholder="Email" name="fields[3]">
            </div>
            <div class="p-interests">
                <div class="p-interest">
                    <label>
                        <input type="checkbox" checked="" name="interests[]" value="5">
                        Newsletters
                    </label>
                </div>
                <div class="p-interest">
                    <label>
                        <input type="checkbox" name="interests[]" value="2">
                        Ofertas
                    </label>
                </div>
            </div>
            <p></p>
            <button type="submit">Suscribirme ahora</button>
        </div>
    </form>
</div>

El form resultante es HTML común y corriente, por ende, en caso de necesitarlo podemos armar este mismo HTML a mano. Hacerlo a través del script nos dá la ventaja de saber que si cambiamos campos en nuestro Opt-In, el form se actualizará en todos los lugares donde aparezca (el script sabrá de esos cambios porque está conectado con el API directamente).

Si decidimos hacer nuesto propia implementación del formulario HTML, hay algunas detalles que debemos tener en cuenta:

  • Como vemos, el formulario envía los campos completados a la url https://pubapi.myperfit.com/v2/optin/micuenta/QFqy3plS. Esta es una sección pública del API, no es necesario ningún tipo de autenticación previa.
  • Los datos del contacto hay que enviarlos con el nombre fields[id], siendo id el id del campo correspondiente.
  • Los intereses a se envian como un array de nombre interests[]
  • Es posible indicar un redirect distinto al configurado cuando creamos el optin, pero por seguridad deberá tener el mismo dominio que el original. Si esto no sucede se utilizará el original.

Atención. Recordá que si implementás tu propio formulario HTML, los cambios que realices a la definición del formulario no se verán reflejados en la implmentación.

Estilo del formulario

Para modificar los estilos de nuestro formulario, podemos usar el siguiente bloque de código css:

div.p-body {
    /* Color de fondo del formulario */
    background-color: #FFFFFF;
}

.p-optin div.p-header,
.p-optin .p-body button,
button.p-open {
    /* Color de fondo de encabezado y botón */
    background: #00AEE8;
    
    /* Color de texto de encabezado y botón */
    color: #FFFFFF;
}

.p-optin .p-body button:hover,
button.p-open:hover{
    /* Color de hover de botón */
    background:  #00AEE8;
    opacity: 0.8;
}

.p-optin div.p-body p,
.p-optin div.p-field label span,
.p-optin .p-body .p-success {
    /* Color de texto del formulario */
    color: #696969;
}