app_link.module

<?php
/**
 * @file
 * Module that sets up redirection to mobile app.
 *
 * Contains: menu hook, custom page, admin forms, validation, boilerplate
 */

/**
 * Implements hook_help().
 */
function app_link_help($path, $arg) {
  switch ($path) {
    case 'admin/help#app_link':
      $help_html = '';
      $help_html .= '<p>' . t('This module will allow you to create empty placeholder pages in your Drupal site. These placeholder pages will redirect users to the appropriate App or App Store according to the user&#8217;s device (iPhone, Android, …).') . '</p>';

      $help_html .= '<p>' . t('In some sense, this module allows the Drupal site to bridge the user to the best digital experience supported by your project.') . '</p>';

      $help_html .= '<h2 id="examples">' . t('Examples') . '</h2>';

      $help_html .= '<p>' . t('Imagine the following scenario, your digital project has a Drupal website, an Android and an iOS app. Then you can create an app_link, for instance <em>https://www.example.org/app</em>. You can share that link in all of your distribution channels (social media, advertisements, …). Then a user goes to that link:') . '</p>';

      $help_html .= '<ul>';
      $help_html .= '<li>' . t('app_link will check if the user&#8217;s device is supported. If it&#8217;s not supported, it will redirect them to the fallback URL. The fallback URL is typically a URL in your Drupal site.') . '</li>';
      $help_html .= '<li>' . t('If the device is supported it will try to open the configured app URI. That means that the app will be fired in the device pointing to the correct page.') . '</li>';
      $help_html .= '<li>' . t('If the device is supported, but the app is not installed the user will be redirected to the configured app store URL.') . '</li>';
      $help_html .= '</ul>';

      $help_html .= '<h2 id="options">' . t('Options') . '</h2>';

      $help_html .= '<p>' . t('There are several options that will let you configure the way the public link (<em>https://www.example.org/app</em>) interacts with the app URIs.') . '</p>';

      $help_html .= '<h3 id="query_string">' . t('Query String') . '</h3>';

      $help_html .= '<p>' . t('By checking <em>Append the query string to the App&#8217;s URL Scheme</em> app_link will send all of the query string parameters present in the public link, to the app URI.') . '</p>';

      $help_html .= '<p>' . t('In the case of our example, if we have an Android URI of <em>intent://root</em>, when we send an Android user to <em>https://www.example.org/app?foo=bar&amp;baz=oof</em> they will be redirected to <em>intent://root?foo=bar&amp;baz=oof</em>.') . '</p>';

      $help_html .= '<p>' . t('This option is useful to pass in dynamic behaviors to the apps, like opening the search page for a search term directly in the app.') . '</p>';

      $help_html .= '<h3 id="dynamic_paths">' . t('Dynamic paths') . '</h3>';

      $help_html .= '<p>' . t('By checking <em>Append the &#8220;path&#8221; param to the App&#8217;s URL Scheme</em> the string in the <em>path</em> query string parameter in the public URL will be added to the path for the app links.') . '</p>';

      $help_html .= '<p>' . t('Linking users to <em>https://www.example.org/app?path=/node/23443</em> will have the effect of redirecting the Android users to <em>intent://root/node/23443</em>. If the fallback was configured to be <em>https://www.example.org</em>, then the user will be redirected to <em>https://www.example.org/node/23443</em> if that device is not supported.') . '</p>';

      $help_html .= '<h2 id="extending">' . t('Extending') . '</h2>';

      $help_html .= '<p>' . t('This module ships with support for the web fallback and the following platforms:') . '</p>';

      $help_html .= '<ul>';

      ctools_include('plugins');
      $platforms_info = ctools_get_plugins('app_link', 'platform');

      foreach ($platforms_info as $platform_info) {
        $help_html .= '<li>' . $platform_info['title'] . '</li>';
      }
      $help_html .= '</ul>';

      $help_html .= '<p>' . t('If you need to support other platforms, you can add one in a custom module. Every platform is a CTools plugin and a JavaScript file. Use one of the existing platforms as an example to build your own.') . '</p>';
      return $help_html;
  }
}

/**
 * Implements hook_menu().
 */
function app_link_menu() {
  $items['app_link/%ctools_export_ui'] = array(
    'title' => 'App Redirect',
    'page callback' => 'app_link_bounce',
    'page arguments' => array(1),
    'load arguments' => array('applink_ctools_export_ui'),
    'access arguments' => array('access content'),
    'type' => MENU_CALLBACK,
  );

  return $items;
}

/**
 * Implements hook_theme().
 */
function app_link_theme($existing, $type, $theme, $path) {
  return array(
    'app_link' => array(
      'variables' => array(
        'platforms' => '',
        'fallback_url' => '',
        'canonical_link' => '',
        'scripts' => array(),
        'metatags' => array(),
      ),
      'path' => $path . '/templates',
      'template' => 'app-link',
    ),
  );
}

/**
 * Prints html file by bypassing page.tpl.php.
 */
function app_link_bounce($applink) {
  $applink = app_link_process_applink($applink);
  $platform_data = $applink->platform_data;
  $fallback_url = app_link_get_fallback_url($applink);

  ctools_include('plugins');
  $platform_info = ctools_get_plugins('app_link', 'platform');
  // Inline JavaScript for performance, we want 0 external requests.
  $js = file_get_contents(drupal_get_path('module', 'app_link') . '/js/app_link.js');
  $scripts['route'] = '<script>' . $js . '</script>';

  $metatags = array(
    'charset' => '<meta charset="utf-8">',
    'title' => '<title>' . t('Mobile App') . '</title>',
    'viewport' => '<meta name="viewport" content="width=device-width, initial-scale=1">',
  );

  $store_badges = app_link_get_store_badges($platform_info, $platform_data);

  // Allow other modules to hook and alter the data set.
  $applink = array(
    'platform_info' => $platform_info,
    'platform_data' => $platform_data,
    'fallback_url' => $fallback_url,
    'canonical_link' => '',
    'scripts' => $scripts,
    'metatags' => $metatags,
    'store_badges' => $store_badges,
  );
  drupal_alter('applink_info', $applink);

  // Merge Platform JS info data.
  $platforms = array();
  foreach ($applink['platform_info'] as $id => $platform) {
    if (!empty($applink['platform_data'][$id])) {
      $platforms[$id] = $applink['platform_data'][$id];
    }
  }

  drupal_add_http_header('Content-Type', 'text/html; charset=utf-8');
  print theme('app_link', array(
    'platforms' => drupal_json_encode($platforms),
    'fallback_url' => drupal_json_encode($applink['fallback_url']),
    'canonical_link' => $fallback_url,
    'scripts' => $applink['scripts'],
    'metatags' => $applink['metatags'],
    'store_badges' => $applink['store_badges'],
  ));

  // Do not just exit. Rather let Drupal run it's closure functions to
  // complete the request. Some modules depend on this.
  return NULL;
}

/**
 * Settings form for pattern to add/edit applink.
 */
function app_link_ctools_export_ui_form(&$form, &$form_state) {
  $applink = $form_state['item'];
  unset($form['info']);
  $form['path'] = array(
    '#default_value' => $applink->path,
    '#title' => t('Path'),
    '#description' => t('Site path to redirect to the mobile app.'),
    '#field_prefix' => url('app_link/', array('absolute' => TRUE)),
    '#type' => 'textfield',
    '#element_validate' => array('app_link_valid_id'),
    '#maxlength' => 255,
    '#required' => TRUE,
  );
  $form['platform_data'] = array(
    '#tree' => TRUE,
  );

  ctools_include('plugins');
  $platforms = ctools_get_plugins('app_link', 'platform');
  uasort($platforms, 'ctools_plugin_sort');
  foreach ($platforms as $id => $platform) {
    $form_callback = !empty($platform['form']) ? $platform['form'] : 'app_link_platform_form';
    $platform_data = !empty($applink->platform_data[$id]) ? $applink->platform_data[$id] : array();
    $form['platform_data'][$id] = $form_callback($platform, $platform_data);
  }

  return $form;
}

/**
 * Construct a Drupal form for the platform parameters.
 *
 * @param array $platform
 *   An array of information about plaform.
 * @param array $conf
 *   An array of existing configurations.
 *
 * @return array
 *   A Drupal form structure.
 */
function app_link_platform_form($platform, array $conf = array()) {
  $form = array(
    '#type' => 'fieldset',
    '#title' => $platform['title'],
    '#collapsible' => TRUE,
    '#collapsed' => FALSE,
    '#tree' => TRUE,
  );
  $form['app_url'] = array(
    '#title' => t('App URL Scheme'),
    '#description' => t('URL Scheme of the @title to redirect to', array(
      '@title' => $platform['title'],
    )),
    '#attributes' => array('placeholder' => 'myapp://'),
    '#type' => 'textfield',
    '#element_validate' => array('app_link_valid_url_scheme'),
    '#maxlength' => 2000,
    '#required' => FALSE,
    '#default_value' => isset($conf['app_url']) ? $conf['app_url'] : '',
  );
  $form['store_url'] = array(
    '#title' => t('Store Page on @store_title', array(
      '@store_title' => $platform['store_title'],
    )),
    '#description' => t('URL where you can download the App.', array(
      '@store_title' => $platform['store_title'],
    )),
    '#attributes' => array('placeholder' => $platform['store_pattern']),
    '#type' => 'textfield',
    '#element_validate' => array('app_link_valid_url'),
    '#maxlength' => 2000,
    '#required' => FALSE,
    '#default_value' => isset($conf['store_url']) ? $conf['store_url'] : '',
  );
  app_link_qs_path_form($conf, $form);
  return $form;
}

/**
 * Ensures that, if a value is entered, it is a valid URL.
 */
function app_link_valid_url($element, &$form_state) {
  if (!empty($element['#value']) && filter_var($element['#value'], FILTER_VALIDATE_URL) === FALSE) {
    form_error($element, t('The @platform @field is an invalid URL', array(
      '@platform' => isset($element['#array_parents'][1]) ? $element['#array_parents'][1] : '',
      '@field' => $element['#title'],
    )));
  }
}

/**
 * Ensures that, if a value is entered, it is a valid URL Path.
 */
function app_link_valid_id($element, &$form_state) {
  if (!empty($element['#value']) && preg_match('/[^a-z0-9\-\_]/', $element['#value'])) {
    form_error($element, t('The @field is an invalid Path Idenfier', array(
      '@field' => $element['#title'],
    )));
  }
}

/**
 * Ensures that, if a value is entered, it is a valid RFC3986 URL Scheme Name.
 */
function app_link_valid_url_scheme($element, &$form_state) {
  if (!empty($element['#value']) && !preg_match('#^[a-z][a-z0-9\+\.\-]+://#', $element['#value'])) {
    form_error($element, t('The @field is an invalid URL Scheme', array(
      '@field' => $element['#title'],
    )));
  }
}

/**
 * Ensures that, if a value is entered, it is a valid Intent URL.
 */
function app_link_valid_intent($element, &$form_state) {
  if (!empty($element['#value']) && !preg_match('#^intent://#', $element['#value'])) {
    form_error($element, t('The @field is an invalid Android Intent URL', array(
      '@field' => $element['#title'],
    )));
  }
}

/**
 * Implements hook_permission().
 */
function app_link_permission() {
  return array(
    'administer app link' => array(
      'title' => t('Administer App Link entries'),
    ),
  );
}

/**
 * Implements hook_ctools_plugin_api().
 */
function app_link_ctools_plugin_api($owner, $api) {
  if ($owner == 'app_link' && $api == 'default_applink') {
    return array('version' => 1);
  }
}

/**
 * Implements hook_ctools_plugin_directory().
 */
function app_link_ctools_plugin_directory($module, $type) {
  if ($module == 'app_link' && $type == 'platform') {
    return 'platforms';
  }
  if ($type == 'export_ui') {
    return 'plugins/' . $type;
  }
}

/**
 * Implements hook_ctools_plugin_type().
 */
function app_link_ctools_plugin_type() {
  return array(
    'platform' => array(
      'use hooks' => TRUE,
    ),
  );
}

/**
 * Add query string and path configuration to a platform form.
 *
 * @param array $conf
 *   The current configuration of the platform plugin.
 * @param array &$form
 *   The form to be modified.
 */
function app_link_qs_path_form(array $conf, array &$form) {
  $form['supports_qs'] = array(
    '#title' => t("Append the query string to the App's URL Scheme"),
    '#description' => t("If checked, the query string will be appended the App's URL Scheme. Example:\n/app_link/myapp?a=b&c=d\nmyapp://?a=b&c=d"),
    '#type' => 'checkbox',
    '#default_value' => isset($conf['supports_qs']) ? $conf['supports_qs'] : FALSE,
  );

  $form['supports_path'] = array(
    '#title' => t('Append the "path" param to the App\'s URL Scheme'),
    '#description' => t("If checked, we'll pass the 'path' query-string parameter will be appended to the App's URL Scheme. Example:\n/app_link/myapp?path=/settings\nmyapp://settings"),
    '#type' => 'checkbox',
    '#default_value' => isset($conf['supports_path']) ? $conf['supports_path'] : FALSE,
  );

  $form['path_whitelist'] = array(
    '#title' => t('Whitelisted app paths'),
    '#description' => t('JavaScript regular expressions, one per line, without leading or trailing slashes, that describe allowed paths within a URL or intent. Paths that do not match will not be redirected to. Do not whitelist all paths, as that could allow open redirects if an app is vulnerable.'),
    '#type' => 'textarea',
    '#default_value' => isset($conf['path_whitelist']) ? $conf['path_whitelist'] : '',
  );

  $form['supports_store_qs'] = array(
    '#title' => t("Append the query string to the App's Store URL"),
    '#description' => t("If checked, the query string will be appended the App's Store URL. To support App download trackers. Example:\n/app_link/myapp?a=b&c=d\nhttps://control.kochava.com/v1/cpi/click?a=b&c=d\nT"),
    '#type' => 'checkbox',
    '#default_value' => isset($conf['supports_store_qs']) ? $conf['supports_store_qs'] : FALSE,
  );
}

/**
 * Constructs the URL to be used as a fallback.
 *
 * It will use the first fallback available sorting by weight.
 *
 * @param object $applink
 *   The applink information.
 *
 * @return string
 *   The fully qualified URL.
 */
function app_link_get_fallback_url($applink) {
  ctools_include('plugins');
  $platform_info = ctools_get_plugins('app_link', 'platform');
  uasort($platform_info, 'ctools_plugin_sort');

  foreach (array_keys($platform_info) as $platform_key) {
    if (empty($applink->platform_data[$platform_key])) {
      continue;
    }
    $platform = $applink->platform_data[$platform_key];
    $uri = !empty($platform['fallback_url']) ? $platform['fallback_url'] : '';
    $qs = _app_link_get_qs_params();
    if (!empty($platform['supports_path']) && !empty($qs['path'])) {
      // See if there is at least one path white-listed.
      $whitelisted = app_link_is_path_whitelisted($_GET['path'], $platform['path_whitelist']);
      if ($whitelisted) {
        $uri .= $_GET['path'];
      }
    }
    $options = array(
      'absolute' => TRUE,
    );
    if (!empty($platform['supports_qs'])) {
      unset($qs['path']);
      $options['query'] = $qs;
    }

    return url($uri, $options);
  }

}

/**
 * Validate that path matches at least one regular expression in a whitelist.
 *
 * @param string $path
 *   The path to validate.
 * @param array $whitelist
 *   An array of regular expression strings.
 *
 * @return bool
 *   TRUE if a match is found or if whitelist is empty. False otherwise.
 */
function app_link_is_path_whitelisted($path, $whitelist) {
  // If there are no paths to white-list, everything is accepted.
  if (empty($whitelist)) {
    return TRUE;
  }

  // Check each item for a RegEx match.
  foreach ($whitelist as $item) {
    $rx = '@' . preg_quote($item, '@') . '@';
    if (preg_match($rx, $path)) {
      return TRUE;
    }
  }

  return FALSE;
}

/**
 * Get the query string params.
 *
 * @return array
 *   An array of key value pairs for the query string values.
 */
function _app_link_get_qs_params() {
  $params = $_GET;
  unset($params['q']);
  return $params;
}

/**
 * If the URL is fully qualified and points to certain domains, normalize it.
 *
 * @param string $web_url
 *   The input URL.
 *
 * @return string
 *   The output URL.
 */
function app_link_parse_url($web_url) {
  // If the link contains the domain within the variable, then make it relative.
  $url_parts = parse_url($web_url);
  $domains = variable_get('app_link_removable_domains', array());
  if (!empty($url_parts['host']) && !in_array($url_parts['host'], $domains)) {
    return $web_url;
  }
  // Use path drupalisms.
  if (empty($url_parts['path'])) {
    $web_url = '<front>';
  }
  else {
    $web_url = ltrim($url_parts['path'], '/');
  }

  // Add any possible query string.
  if (!empty($url_parts['query'])) {
    $web_url .= '?' . $url_parts['query'];
  }
  return url($web_url, array('absolute' => TRUE));
}

/**
 * Processes the platform data.
 *
 * @param object $applink
 *   The plugin content.
 *
 * @return object
 *   The processed plugin content.
 */
function app_link_process_applink($applink) {
  // Convert the path_whitelist to an array.
  foreach ($applink->platform_data as &$data) {
    if (empty($data['path_whitelist'])) {
      $data['path_whitelist'] = array();
      continue;
    }
    // Explode our text field of whitelisted paths into an array.
    $data['path_whitelist'] = explode("\n", $data['path_whitelist']);
  }
  return $applink;
}

/**
 * Forms app store download badges for each platform.
 *
 * @param array $platform_info
 *   Contains info about the platform plugin.
 * @param array $platform_data
 *   Contains info about the app link (e.g. store url).
 *
 * @return array
 *   Array of html strings.
 */
function app_link_get_store_badges($platform_info, $platform_data) {
  $badges = array();

  foreach ($platform_info as $id => $platform) {
    if (empty($platform_data[$id]['store_url'])) {
      continue;
    }

    $badges[$id]['store_url'] = $platform_data[$id]['store_url'];
    $badges[$id]['store_text'] = $platform['store_text'];
    $badges[$id]['badge_url'] = $platform['badge_url'];
  }

  return $badges;
}