SMS Href creates SMS URL strings, updates existing SMS URL strings, or updates all href attributes containing SMS URLs on a web page or in a defined DOM context.
You can avoid this library and use the universal separator;?&
(all three characters in that order),
but it doesn't work everywhere.
Manager | Command |
---|---|
npm install sms-href |
|
yarn add sms-href |
|
pnpm add sms-href |
|
bun add sms-href |
runner | output | description |
---|---|---|
npm run build |
./lib/**/* |
Transpile from Typescript to Javascript |
npm run build:pack |
./sms-href-{package-json-version}.tgz |
Create NPM package file (*.tgz ) |
npm run demo |
./demo/dist/demo.js |
Build demo and measure minimal build size |
import {SmsHref} from "sms-href";
const smsHref: SmsHref = new SmsHref();
// As promise
smsHref.fixAll().catch();
// OR sync
try {
await smsHref.fixAll();
} catch (e) {
}
Android | iOS | iPadOS |
---|---|---|
10 (Quince Tart) | 6 | 6 |
12 (Snow Cone) | 8 | 8 |
13 (Tiramisu) | 12 | 12 |
15 | 15 | |
16 | 16 | |
17 (beta) | 17 (beta) |
Syntax:
Instance of SmsHref
Example:
const smsHref: SmsHref = new SmsHref();
Constructor parameters:
type | default | description | |
---|---|---|---|
[options ] |
Options |
Configuration of custom separator and allowed devices - Show detail | |
[options.allow ] |
Devices |
List of enable/disable devices - Show detail | |
[options.allow.mobile = true ] |
boolean |
true |
Enable/disable href update for mobile devices |
[options.allow.tablet = true ] |
boolean |
true |
Enable/disable href update for tablet devices |
[options.allow.facebook = true ] |
boolean |
true |
Enable/disable href update for Facebook app web view |
[options.separator = null ] |
string null |
null |
User defined SMS body (body= ) separator. Read more NOTE: Internal platform detection and allowed devices list will be disabled. |
[options.encode = true ] |
boolean |
true |
Enable/disable message text encoding globally ( e.g., encodeURIComponent )NOTE: Methods fixValue() and create() have their own parameter for enable/disable encoding and this global parameter can be overridden. |
Example (disable tablets and facebook app web view):
const smsHref: SmsHref = new SmsHref({
allow: {
facebook: false,
tablet: false
}
});
If you want to define your own separator, you can use existed separator constants
constant name | value | type | description |
---|---|---|---|
ANDROID_SEPARATOR |
? |
string |
Body separator ?body= for Android platform |
IOS_7_AND_LOWER_SEPARATOR |
; |
string |
Body separator ;body= for IOS <= 7 platform |
IOS_8_AND_HIGHER_SEPARATOR |
& |
string |
Body separator &body= for IOS >= 8 platform |
MIN_IOS_VERSION |
7 |
number |
Value is 7 - because iOS7 allegedly doesn't support sms: href links. |
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()
});
Syntax:
Finds and update all anchor links with sms:
protocol value by current platform in set DOM context.
type | default | description | |
---|---|---|---|
[context = document ] |
Element HTMLElement Document |
document |
Defines parent DOM node for search |
returns | Promise<ResultCode> |
||
throws | Promise.catch<ResultCode> |
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:
constant name | value | type | status | description |
---|---|---|---|---|
CODE_SUCCESS |
200 |
number |
Ok | All sms: href values in anchors was updated |
CODE_NOT_FOUND |
404 |
number |
Not found | Anchors with sms: href value doesn't exist |
CODE_UNSUPPORTED_OS |
501 |
number |
Not Implemented | Current platform doesn't support sms: href protocol |
Syntax:
Update input string value by current platform.
type | default | description | |
---|---|---|---|
smsValue |
string |
Input string for update | |
[encode ] |
boolean |
Constructor options.encode value |
Enable/disable message text encoding ( e.g., encodeURIComponent ) |
returns | Promise<string> |
Valid SMS Href sms: anchor string |
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
Syntax:
Creates sms:
href string from phone number and sms message text.
type | default | description | |
---|---|---|---|
smsConfiguration |
SmsConfiguration |
||
smsConfiguration[.phone] |
string number |
SMS Phone number | |
smsConfiguration[.message] |
string |
SMS message text | |
[ encode ] |
boolean |
Constructor options.encode value |
Enable/disable message text encoding ( e.g., encodeURIComponent ) |
returns | Promise<string> - Valid SMS Href sms: anchor string |
||
throws | Promise.reject<TypeError> |
If phone and message are both not provided |
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
type ResultCode = number;
type Options = {
allow?: Devices;
separator?: string | null;
encode?: boolean;
}
type Devices = {
mobile?: boolean;
tablet?: boolean;
facebook?: boolean;
};
type SmsConfiguration = {
phone?: string | number;
message?: string;
}
References