![Introducing Enhanced Alert Actions and Triage Functionality](https://cdn.sanity.io/images/cgdhsj6q/production/fe71306d515f85de6139b46745ea7180362324f0-2530x946.png?w=800&fit=max&auto=format)
Product
Introducing Enhanced Alert Actions and Triage Functionality
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
@pactsafe/pactsafe-react-sdk
Advanced tools
Readme
_ps
to use the PactSafe library.render_data
objectclickWrapStyle
propsignerIdSelector
propdisplayImmediately
propdisplayAll
propposition
propalwaysVisible
propCheck out a live demo of both the PSClickwrap and PSBrowsewrap components here
To build the examples locally, you must first add your PactSafe access id by creating a .env
file in the root directory and add the following contents:
PACTSAFE_ACCESS_ID=<YOUR_PACTSAFE_ACCESS_ID_HERE>
After doing this, you need to create both a clickwrap group with the group key example-clickwrap
and a browsewrap with the key example-browsewrap
. In your example clickwrap group, if you
want the render data to work properly, create three tokens in a contract within the example-clickwrap
group with the API field names to be: user_token_value
, another_token_value
, and last_token_value
.
Some helpful information on creating contracts with render data can be found here.
(Note: You shouldn't have to write any javascript to get the demo to work! When implementing yourself, the React SDK uses the dynamic
and renderData
props to handle rendering of dynamic contracts instead of having to make _ps
calls.)
After completing these steps the demo should load as the online example does by running
npm install
npm start
Then open http://localhost:3000
in a browser.
The easiest way to use pactsafe-react-sdk is to install it from NPM
npm install @pactsafe/pactsafe-react-sdk --save
You can also directly download the source files from unpkg to link to the source files directly or download the source from Github and build it yourself.
The following can be found in the project's root directory, as well as compiled using npm run build
:
lib/
es/
(enabled by default/without configuration using npm install
)/umd
In order to use the PSClickWrap, you must specify a signer ID selector that corresponds to the ID of an <input>
field on the page that will identify the signer (usually an email field). This ID should then be passed as the signerIdSelector
prop to the PSClickWrap component:
import { PSClickWrap } from 'pactsafe-react-sdk'
...
<input type="email" id="userEmail" placeholder="Your Email"/>
<PSClickWrap accessId={YOUR_PACTSAFE_ACCESS_ID_HERE} groupKey={YOUR_GROUP_KEY_HERE} signerIdSelector={userEmail}/>
Replace with YOUR_PACTSAFE_ACCESS_ID_HERE
with your PactSafe Site Access ID found here
Replace YOUR_GROUP_KEY_HERE
with your group's key found within your PactSafe group's configuration
Pass in any additional options using props on the PSClickWrap
component.
You can hook into events using the triggered event callback props described here: (See documentation on PSClickwrap callback props here).
Your PSBrowseWrap component should be placed where you would like your Legal Center link to appear on the page. Pass what you want the link's text to display as using the linkText
prop.
import { PSBrowseWrap } from 'pactsafe-react-sdk'
...
<PSBrowseWrap accessId={YOUR_PACTSAFE_ACCESS_ID_HERE} groupKey={YOUR_GROUP_KEY_HERE} linkText={'View Legal Center'}/>
Prop | Type | Default | Required? | Description |
---|---|---|---|---|
accessId | string | Required Value | Yes | PactSafe site access ID |
clickWrapStyle | string.oneOf['full' , 'scroll' , 'checkbox' , 'combined' , 'embedded' ] | Value specified in PactSafe Group's UI | No | Override the clickwrap style specified in the PactSafe Group Interface |
confirmationEmail | bool | Value specified in PactSafe Group's UI | No | Override whether to send a confirmation email to the signer upon contract acceptance |
containerId | string | ps-clickwrap | No | The div ID that will contain your clickwrap. You should override this if you plan on displaying more than one contract on a page. |
disableSending | bool | false | No | Turn this on if you want to manually send the agreed event instead of it automatically being sent on contract acceptance. See documentation on manually sending the agreed event here. |
displayAll | bool | true | No | Display all contracts in the group immediately. If disabled, a contract will only be displayed if the signer hasn't accepted the latest version. |
displayImmediately | bool | true | No | Display the group's contracts as soon as the Signer ID is available. If disabled, contracts will remain hidden until you call displayRequired() |
dynamic | bool | false | No | If you would like to use dynamic render_data in your contract, you must set this to true. If this is set to true, you MUST also pass an object into the render_data prop. |
filter | string | undefined | No, Yes if groupKey prop is not passed | Allows you to dynamically load contracts without having to specify a group. Filter must be in the format: id==123,456 OR id==12345 and tags==tag1,tag2 OR tags==tag1,tag2 . See documentation for more information on using dynamic groups. |
forceScroll | bool | Value specified in PactSafe Group's UI | No | Disable acceptance until the signer scrolls to the bottom of each contract. |
groupKey | string | undefined | Yes, unless filter prop is passed | PactSafe group key, this is found within the PactSafe Groups configuration. |
psScriptUrl | string | '//vault.pactsafe.io/ps.min.js' | No | If using a custom (or development) version of the ps.js file, pass the file URL in here. You probably won't need to use this. |
backupScriptUrl | string | ''//d3l1mqnl5xpsuc.cloudfront.net/ps.min.js' | No | If using a custom (or development) version of the ps.js file, pass the alternative backup URL in here. Otherwise, this will default to the cloudfront backup provided by the ps.js snippet. This is designed to load if the first script (defined in psScriptURL) fails to load |
renderData | object | undefined | If dynamic is set to true | Object containing the dynamic render data for your contract. For more information on using dynamic contracts, check out this documentation. |
signerIdSelector | string | Required Value | Yes | The ID of the <input> element that will be used to identify the signer. |
signerId | string | undefined | No, unless signerIdSelector is not passed | Use this to set the signer id directly |
testMode | bool | false | No | Enable this to register any contract acceptances as test data that can be cleared within the PactSafe UI |
onAll | function | undefined | No | See onAll below |
onSent | function | undefined | No | See onSent below |
onRetrieved | function | undefined | No | See onRetrieved below |
onSet | function | undefined | No | See onSet below |
onSetSignerId | function | undefined | No | See onSetSignerId below |
onValid | function | undefined | No | See onValid below |
onInvalid | function | undefined | No | See onInvalid below |
onRendered | function | undefined | No | See onRendered below |
onDisplayed | function | undefined | No | See onDisplayed below |
onScrolled | function | undefined | No | See onScrolled below |
onScrolledContract | function | undefined | No | See onScrolledContract below |
onError | function | undefined | No | See onError below |
New in v2.0 of the React SDK we are introducing triggered event props. These props are functions that can be passed in as props and are called in response to events that happen after a user interacts with a PSClickwrap component. These function props correspond to the triggered events that can be also created using the _ps global created by the snippet. For more information on how triggered events work within the PSSnippet and calling them without the props, you can learn about them here. By using function props, the component will interact with the _ps
API for you and clean up after itself when the component is destroyed.
The demo page contains various callback examples and the corresponding callback events can be observed in the console output.
As a quick example of the usage of these, if you wanted to enable a button on a valid clickwrap event, here is example code to do so using the onValid and onInvalid event props:
import { PSClickWrap } from 'pactsafe-react-sdk'
...
class Example extends React.Component {
constructor(props){
super(props);
this.state = { hasAgreed: false };
}
onValid = () => {
this.setState({ hasAgreed: true });
}
onInvalid = () => {
this.setState({ hasAgreed: false });
}
render () {
return
<div>
<input type="email" id="userEmail" placeholder="Your Email"/>
<PSClickWrap accessId={YOUR_PACTSAFE_ACCESS_ID_HERE} groupKey={YOUR_GROUP_KEY_HERE} signerIdSelector={userEmail} onValid={this.onValid} onInvalid={this.onInvalid}/>
<button disabled={!this.state.hasAgreed} type="submit">Submit</button>
</div>
}
}
If you do not want to use event callback props, the _ps
is loaded into the window object for you to access and set event listeners manually. Using the _ps
global you should be able to do everything listed in our full documentation on the PS.js library
The list below describes the props names and corresponding PactSafe event:
_ps event: all
A special event that is triggered when any other event is triggered. The name of the original event is always the first argument passed to the callback function. The rest of the arguments will match whatever arguments were passed to the original event's callback function.
Name | Type | Description |
---|---|---|
event | String | The name of the event that was triggered. |
[arguments] | Array | All of the arguments that were passed to the original event. |
_ps event: sent
Triggered when a send
command has been completed successfully.
Name | Type | Description |
---|---|---|
event_type | String | The type of action that was sent. Supported values include: 'agreed', 'disagreed', 'displayed', 'visited' and 'updated'. |
parameters | Object | An object containing the contract and group details that were sent. Contains three parameters: 'contracts', 'versions' and 'group'. |
context | Site, BrowsewrapGroup or ClickwrapGroup | The Site or Group object that initiated the send command. |
payload | String | The URL-encoded payload that would have been sent to the Action API. This argument is only present when the prop disable_sending is set to true. |
_ps event: retrieved
Triggered when a retrieved
command has been completed successfully.
Name | Type | Description |
---|---|---|
responseJSON | Object | The JSON response body returned by the XMLHttpRequest. |
xhr | XMLHttpRequest | The raw XMLHttpRequest that was sent to the Action API. |
context | Site, BrowsewrapGroup or ClickwrapGroup | The Site or Group object that initiated the retrieve command. |
_ps event: set
Triggered when a parameter is set. Note: This event will only be triggered for specific parameters. Supported parameters include: signer_id, signer_id_selector, form_selector. Since this is an event listener for site level properties, you should only set this on one clickwrap on the page if multiple are mounted in order to guarantee the function is idempotent, otherwise it will be called once per clickwrap.
Name | Type | Description |
---|---|---|
parameter | String | The name of the parameter that was set. |
value | String, Number, Object, Function, etc. | The raw XMLHttpRequest that was sent to the Action API. |
context | Site, BrowsewrapGroup or ClickwrapGroup | The Site or Group object on which the parameter was set. |
_ps event: set:signer_id
Triggered when the signer_id parameter is set.
Name | Type | Description |
---|---|---|
value | String | The signer_id that was set |
context | Site, BrowsewrapGroup or ClickwrapGroup | The Site or Group object on which the parameter was set. |
_ps event: valid
Triggered when all of the contracts in a Group have been accepted by a signer.
Name | Type | Description |
---|---|---|
parameters | Object | An object containing the contracts and versions that belong to the Group. Contains three parameters: 'contracts', 'versions' and 'group' |
context | BrowsewrapGroup or ClickwrapGroup | The Group object that was validated |
_ps event: invalid
Triggered when all of the contracts in a Group are no longer accepted by a signer. This event will be triggered if a signer un-checks a contract on a valid Group.
Name | Type | Description |
---|---|---|
parameters | Object | An object containing the contracts and versions that belong to the Group. Contains three parameters: 'contracts', 'versions' and 'group' |
context | BrowsewrapGroup or ClickwrapGroup | The Group object that was invalidated |
_ps event: rendered
Triggered when a Group object has been rendered.
Name | Type | Description |
---|---|---|
context | ClickwrapGroup | The Group object that was rendered |
_ps event: displayed
Triggered when a Group object displays a contract.
Name | Type | Description |
---|---|---|
element | HTMLElement | The contract's HTMLElement that was displayed. |
context | ClickwrapGroup | The Group object that displayed the contract |
_ps event: scrolled
Triggered when "Force Scroll" has been enabled in your Group Settings (or passed as a prop) and all of the contracts in a Group have been scrolled to the bottom of within a "Scroll" or "Embedded" Group style/layout.
Name | Type | Description |
---|---|---|
contractsElement | Object | The element containing the entire container selector of the group. |
context | ClickwrapGroup | The Group object that had all contracts scrolled to the bottom |
_ps event: scrolled:contract
Triggered when "Force Scroll" has been enabled in your Group Settings (or passed as a prop) and one of the contracts in a Group has been scrolled to the bottom of a "Scroll" or "Embedded" Group style/layout.
Name | Type | Description |
---|---|---|
contractHTML | Object | An object containing the HTML of the contract that has been scrolled to the bottom. |
group | ClickwrapGroup | The Group object that was scrolled to the bottom |
_ps event: error
Triggered when a send or retrieve command encounters an error before being sent.
Name | Type | Description |
---|---|---|
message | String | A message describing why the error occurred. |
event_type | String | The type of action that was being sent. |
context | Site, BrowsewrapGroup, or ClickwrapGroup | The Site or Group object that initiated the command. |
Prop | Type | Default | Required? | Description |
---|---|---|---|---|
accessId | string | Required Value | Yes | PactSafe site access ID |
alwaysVisible | bool | false | No | Keep the badge visible on the page at all times. If disabled, the badge will be hidden if the target link is visible on screen. |
badgeText | string | value of linkText | No | Provide alternate text for the BrowseWrap badge |
groupKey | string | null | Yes | PactSafe group key, this is found within the PactSafe Groups configuration. |
link | string | null | If openLegalCenter is set to false | Location of where the BrowseWrap link should redirect to, should only be used if openLegalCenter is set to false, otherwise the link will open the group's PactSafe legal center |
linkText | string | null | Yes | The text that your BrowseWrap link will display (for example, 'Legal Center' or 'Terms of Service') |
openLegalCenter | bool | true | No | Open this group's legal center page when the badge or link is clicked. If enabled, the target link's original href will be replaced. |
position | string.oneOf['middle' , 'left' , 'right' , 'auto' ] | auto | Yes | Position of where the BrowseWrap badge will float within the browser window |
psScriptUrl | string | '//vault.pactsafe.io/ps.min.js' | Yes | If using a custom (or development) version of the ps.js file, pass the file URL in here. You probably won't need to use this. |
src
, lib
and the build process)Copyright © 2019 PactSafe.
FAQs
Ironclad Clickwrap React SDK - SDK for easy Ironclad Clickwrap implementations leveraging the Ironclad JavaScript Library & API
We found that @pactsafe/pactsafe-react-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 28 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
Security News
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.