sms-href v1.1.3

• Installation
• Usage
• API
  • Instance
    • Custom separator
  • fixAll
  • fixValue
  • create
• Types
  • ResultCode
  • Options
  • Devices
  • SmsConfiguration

Installation

DEV runners

Basic usage (without catching outputs)

import {SmsHref} from "sms-href";

const smsHref: SmsHref = new SmsHref();

// As promise
smsHref.fixAll().catch();

// OR sync
try {
    await smsHref.fixAll();
} catch (e) {
}

Tested platforms

API

Instance

Syntax:

new SmsHref( [ options: Options ] )

Instance of SmsHref

Example:

const smsHref: SmsHref = new SmsHref();

Constructor parameters:

Example (disable tablets and facebook app web view):

const smsHref: SmsHref = new SmsHref({
    allow: {
        facebook: false,
        tablet: false
    }
});

Custom separator definition

If you want to define your own separator, you can use existed separator constants

NOTE: IOS 7 allegedly does not support sms: protocol.

Example:

import {
    SmsHref,
    MIN_IOS_VERSION,
    ANDROID_SEPARATOR,
    IOS_7_AND_LOWER_SEPARATOR,
    IOS_8_AND_HIGHER_SEPARATOR
} from "sms-href";

// Custom
function customSeparatorMechanism(): string | null {
    const platform: CustomPlatformDetection = new CustomPlatformDetection();

    if (platform.name === 'Android')
        return ANDROID_SEPARATOR;

    if (platform.name === 'IOS') {
        if (platform.version.major <= MIN_IOS_VERSION)
            return IOS_7_AND_LOWER_SEPARATOR
        return IOS_8_AND_HIGHER_SEPARATOR;
    }

    return null;
}

// Instance
const smsHref: SmsHref = new SmsHref({
    separator: customSeparatorMechanism()
});

fixAll

Syntax:

async fixAll( [ context: Element | HTMLElement | Document ] ) : Promise<ResultCode>

Finds and update all anchor links with sms: protocol value by current platform in set DOM context.

Example:

await smsHref.fixAll();

Example with custom defined context:

const context: HTMLElement = document.querySelector('.context-element');

await smsHref.fixAll(context);

Example with using resultCode in Promise<ResultCode>.

import {
    SmsHref,
    ResultCode,
    CODE_SUCCESS,
    CODE_NOT_FOUND,
    CODE_UNSUPPORTED_OS
} from "sms-href";

const smsHref: SmsHref = new SmsHref();

smsHref.fixAll()
    .then((resultCode: ResultCode): void => {
        if (resultCode === CODE_SUCCESS)
            console.log(`All sms: href values in anchors was updated`);
    })
    .catch((resultCode: any): void => {
        if (resultCode === CODE_NOT_FOUND)
            console.log(`'Anchors with sms: href value doesn't exist'`);
        else if (resultCode === CODE_UNSUPPORTED_OS)
            console.log(`Current platform doesn't support sms: href protocol`);
    });

ResultCode constants list:

fixValue

Syntax:

async fixValue( smsValue: string [, encode: boolean ] ) : Promise<string>

Update input string value by current platform.

Example:

await smsHref.fixValue('1234@body=Your message');
// Android  --> sms:1234?body=Your%20message
// IOS <= 7 --> sms:1234;body=Your%20message
// IOS >= 8 --> sms:1234&body=Your%20message

Example (with disabled message encoding):

await smsHref.fixValue('1234@body=Your message', false);
// Android  --> sms:1234?body=Your message
// IOS <= 7 --> sms:1234;body=Your message
// IOS >= 8 --> sms:1234&body=Your message

create

Syntax:

async create( smsConfiguration: SmsConfiguration [, encode: boolean] ) : Promise<string>

Creates sms: href string from phone number and sms message text.

NOTES:

• Phone and message are both optional, but one of them must be provided.
• Phone number format validation is not implemented. You should use own validation.
• SMS message format validation is not implemented. You should use own validation.

Example:

await smsHref.create({
    phone: 1234,
    message: 'Your message'
});
// Android  --> sms:1234?body=Your%20message
// IOS <= 7 --> sms:1234;body=Your%20message
// IOS >= 8 --> sms:1234&body=Your%20message

Example (with disabled message encoding):

await smsHref.create({
    phone: 1234,
    message: 'Your message'
}, false);
// Android  --> sms:1234?body=Your message
// IOS <= 7 --> sms:1234;body=Your message
// IOS >= 8 --> sms:1234&body=Your message

Types

ResultCode

type ResultCode = number;

Options

type Options = {
    allow?: Devices;
    separator?: string | null;
    encode?: boolean;
}

Devices

type Devices = {
    mobile?: boolean;
    tablet?: boolean;
    facebook?: boolean;
};

SmsConfiguration

type SmsConfiguration = {
    phone?: string | number;
    message?: string;
}

License

MIT © Dárius Bokor

References

• The "sms" URI Scheme
• Apple IOS - SMS Links
• stackoverflow -> 58131833
• stackoverflow -> 19126326