NDEFReader.write()
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The write()
method of the NDEFReader
interface attempts to write an NDEF message to a tag and returns a Promise
that either resolves when a message has been written to the tag or rejects if a hardware or permission error is encountered. This method triggers a permission prompt if the "nfc" permission has not been previously granted.
Syntax
NDEFReader.write(message);
NDEFReader.write(message, options);
Parameters
message
-
The message to be written, one of
DOMString
,BufferSource
, or an array of records. A record has the following members:data
Optional-
Contains the data to be transmitted, one of a string, a
BufferSource
, or an array of nested records. encoding
Optional-
A string specifying the record's encoding.
id
Optional-
A developer-defined identifier for the record.
lang
Optional-
A valid language tag according to RFC 5646: Tags for Identifying Languages (also known as BCP 47).
mediaType
Optional-
A valid MIME type.
recordType
-
A string indicating the type of data stored in
data
. It must be one of the following values:"absolute-url"
-
An absolute URL to the data.
"empty"
-
An empty
NDEFRecord
. "mime"
-
A valid MIME type.
"smart-poster"
-
A smart poster as defined by the NDEF-SMARTPOSTER specification.
"text"
-
Text as defined by the NDEF-TEXT specification.
"unknown"
-
The record type is not known.
"URL"
-
A URL as defined by the NDEF-URI specification.
options
Optional-
An object with the following properties:
-
overwrite
-- ABoolean
specifying whether or not existing records should be overwritten, if such exists. signal
-- An optionalAbortSignal
that allows the current write operation to be canceled.
-
Return value
A Promise
that either resolves when a message has been written to the tag or rejects if a hardware or permission error is encountered.
Exceptions
This method doesn't throw exceptions; instead, it rejects the returned promise,
passing a DOMException
whose name
is one of the
following:
AbortError
-
The scan operation was aborted with the
AbortSignal
passed in theoptions
argument. NotAllowedError
-
The permission for this operation was rejected or
overwrite
isfalse
and there are already records on the tag. NotSupportedError
-
There is no NFC adapter compatible with Web NFC, or the available NFC adapter does not support pushing messages, or connection can not be established.
NotReadableError
-
The UA is not allowed to access underlying NFC adapter (e.g., due to user preference).
NetworkError
-
Transfer failed after it already started (e.g., the tag was removed from the reader).
Examples
Write a text string
The following example shows how to write a DOMString
to an NFC tag and process any errors that occur.
const ndef = new NDEFReader();
ndef.write(
"Hello World"
).then(() => {
console.log("Message written.");
}).catch(error => {
console.log(`Write failed :-( try again: ${error}.`);
});
Write a URL
The following example shows how to write a record object (described above) to an NFC tag and process any errors that occur.
const ndef = new NDEFReader();
try {
await ndef.write({
records: [{ recordType: "url", data: "http://example.com/" }]
});
} catch {
console.log("Write failed :-( try again.");
};
Scheduling a write with a timeout
It's sometimes useful to set a time limit on a write operation. For example, you ask the user to touch a tag, but no tag is found within a certain amount of time, then you time out.
const ndef = new NDEFReader();
ndef.onreading = (event) => console.log("We read a tag!");
function write(data, { timeout } = {}) {
return new Promise((resolve, reject) => {
const ctlr = new AbortController();
ctlr.signal.onabort = () => reject("Time is up, bailing out!");
setTimeout(() => ctlr.abort(), timeout);
ndef.addEventListener("reading", event => {
ndef.write(data, { signal: ctlr.signal }).then(resolve, reject);
}, { once: true });
});
}
await ndef.scan();
try {
// Let's wait for 5 seconds only.
await write("Hello World", { timeout: 5_000 });
} catch(err) {
console.error("Something went wrong", err);
} finally {
console.log("We wrote to a tag!");
}
Specifications
Specification |
---|
Web NFC API # dom-ndefreader-write |
Browser compatibility
BCD tables only load in the browser