UNPKG

39.1 kBMarkdownView Raw
1# PactSafe React SDK
2
3[![npm package][npm-badge]][npm]
4
5## Features
6- Automatically loads the PactSafe Snippet into your app so all you have to do is call `_ps` to use the [PactSafe library](https://developer.pactsafe.com/docs/get-to-know-our-javascript-library).
7
8#### PSClickWrap Component:
9
10
11- Renders a PactSafe ClickWrap group by providing a site access ID and group key
12- Ability to render PactSafe ClickWrap groups dynamically using a filter to specify contract ID's and/or tags
13- Ability to render a dynamic PactSafe ClickWrap by passing in a custom `render_data` object
14- Ability to override properties set within the PactSafe App's group configuration such as:
15 - ClickWrap style using the `clickWrapStyle` prop
16 - Signer ID selector using the `signerIdSelector` prop
17 - Displaying contracts immediately using the `displayImmediately` prop
18 - Displaying all contracts using the `displayAll` prop
19 - and more! ([See more detailed documentation on available PSClickWrap props here](#props))
20- Ability to hook into events fired by the Snippet using function props ([See documentation on PSClickwrap callback props here](#callback-props))
21
22#### PSBrowseWrap Component:
23
24
25- Renders a PactSafe BrowseWrap group by providing a site access ID and group key
26- Ability to override properties set within the PactSafe App's group configuration such as:
27 - Position of BrowseWrap with the `position` prop
28 - Whether the BrowseWrap should always be visible with the `alwaysVisible` prop
29 - and more! ([See more detailed documentation on available PSBrowseWrap props here](#props))
30
31## Demo & Examples
32
33[Check out a live demo of both the PSClickwrap and PSBrowsewrap components here](https://pactsafe.github.io/pactsafe-react-sdk/)
34
35#### PSClickWrap:
36![PSClickCrap](images/psclickwrap.gif "PSClickWrap")
37
38#### PSBrowseWrap:
39
40![PSBrowseWrap](images/psbrowsewrap.gif "PSBrowseWrap")
41
42To 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:
43
44```
45PACTSAFE_ACCESS_ID=<YOUR_PACTSAFE_ACCESS_ID_HERE>
46```
47
48After 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
49want 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`.
50
51[Some helpful information on creating contracts with render data can be found here.](https://developer.pactsafe.com/docs/how-to-use-smart-contracts-with-the-javascript-library)
52(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.)
53
54After completing these steps the demo should load as the online example does by running
55
56```
57npm install
58npm start
59```
60
61Then open [`http://localhost:3000`](http://localhost:3000) in a browser.
62
63## Installation
64
65The easiest way to use pactsafe-react-sdk is to install it from NPM
66
67```
68npm install @pactsafe/pactsafe-react-sdk --save
69```
70
71You can also directly download the source files from [unpkg](https://unpkg.com/@pactsafe/pactsafe-react-sdk@2.0.0/) to link to the source files directly or download the source from Github and build it yourself.
72
73The following can be found in the project's root directory, as well as compiled using `npm run build`:
74* A CommonJS build in `lib/`
75* An ES modules build in `es/` (enabled by default/without configuration using `npm install`)
76* UMD development and production builds in `/umd`
77
78## Usage
79
80#### Using PSClickWrap
81
82In 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:
83
84```JSX
85import { PSClickWrap } from 'pactsafe-react-sdk'
86
87...
88
89<input type="email" id="userEmail" placeholder="Your Email"/>
90
91<PSClickWrap accessId={YOUR_PACTSAFE_ACCESS_ID_HERE} groupKey={YOUR_GROUP_KEY_HERE} signerIdSelector={userEmail}/>
92```
93
94Replace with `YOUR_PACTSAFE_ACCESS_ID_HERE` with your PactSafe Site Access ID found [here](https://app.pactsafe.com/settings/account)
95
96Replace `YOUR_GROUP_KEY_HERE` with your group's key found within your [PactSafe group's configuration](https://app.pactsafe.com/groups)
97
98Pass in any additional options using props on the `PSClickWrap` component.
99
100You can hook into events using the triggered event callback props described here: ([See documentation on PSClickwrap callback props here](#callback-props)).
101
102#### Using PSBrowseWrap
103
104Your 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.
105
106
107```JSX
108import { PSBrowseWrap } from 'pactsafe-react-sdk'
109
110...
111
112<PSBrowseWrap accessId={YOUR_PACTSAFE_ACCESS_ID_HERE} groupKey={YOUR_GROUP_KEY_HERE} linkText={'View Legal Center'}/>
113```
114---
115## <a name="props"></a>Props
116
117### PSClickWrap Props:
118
119| Prop | Type | Default | Required? | Description |
120|:-------------------:|:---------------------------------------------------------------------------:|:-------------------------------------------:|:--------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
121|`accessId` | string | Required Value | Yes | PactSafe site access ID |
122|`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 |
123|`confirmationEmail` | bool | Value specified in PactSafe Group's UI | No | Override whether to send a confirmation email to the signer upon contract acceptance |
124|`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. |
125|`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.](https://developer.pactsafe.com/docs/get-to-know-our-javascript-library#section-3-sending-agreed-in-javascript) |
126|`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. |
127|`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()` |
128|`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. |
129|`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.](https://developer.pactsafe.com/docs/dynamic-groups-and-how-to-use-them) |
130|`forceScroll` | bool | Value specified in PactSafe Group's UI | No | Disable acceptance until the signer scrolls to the bottom of each contract. |
131|`groupKey` | string | undefined | Yes, unless `filter` prop is passed | PactSafe group key, this is found within the PactSafe Groups configuration. |
132|`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. |
133|`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 |
134|`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.](https://developer.pactsafe.com/docs/how-to-use-smart-contracts-with-the-javascript-library) |
135|`signerIdSelector` | string | Required Value | Yes | The ID of the `<input>` element that will be used to identify the signer. |
136|`signerId` | string | undefined | No, unless `signerIdSelector` is not passed | Use this to set the signer id directly |
137|`testMode` | bool | false | No | Enable this to register any contract acceptances as test data that can be cleared within the PactSafe UI |
138|`onAll` | function | undefined | No | See [onAll](#onAll) below
139|`onSent` | function | undefined | No | See [onSent](#onSent) below
140|`onRetrieved` | function | undefined | No | See [onRetrieved](#onRetrieved) below
141|`onSet` | function | undefined | No | See [onSet](#onSet) below
142|`onSetSignerId` | function | undefined | No | See [onSetSignerId](#onSetSignerId) below
143|`onValid` | function | undefined | No | See [onValid](#onValid) below
144|`onInvalid` | function | undefined | No | See [onInvalid](#onInvalid) below
145|`onRendered` | function | undefined | No | See [onRendered](#onRender) below
146|`onDisplayed` | function | undefined | No | See [onDisplayed](#onDisplayed) below
147|`onScrolled` | function | undefined | No | See [onScrolled](#onScrolled) below
148|`onScrolledContract` | function | undefined | No | See [onScrolledContract](#onScrolledContract) below
149|`onError` | function | undefined | No | See [onError](#onError) below
150
151
152## <a name="callback-props"></a>PSClickwrap Triggered Event Callback Props:
153
154New 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](https://developer.pactsafe.com/v1.1/reference#triggered-events-1). By using function props, the component will interact with the `_ps` API for you and clean up after itself when the component is destroyed.
155The demo page contains various callback examples and the corresponding callback events can be observed in the console output.
156
157As 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:
158```JSX
159import { PSClickWrap } from 'pactsafe-react-sdk'
160
161...
162
163class Example extends React.Component {
164 constructor(props){
165 super(props);
166 this.state = { hasAgreed: false };
167 }
168
169 onValid = () => {
170 this.setState({ hasAgreed: true });
171 }
172
173 onInvalid = () => {
174 this.setState({ hasAgreed: false });
175 }
176
177 render () {
178 return
179 <div>
180 <input type="email" id="userEmail" placeholder="Your Email"/>
181
182 <PSClickWrap accessId={YOUR_PACTSAFE_ACCESS_ID_HERE} groupKey={YOUR_GROUP_KEY_HERE} signerIdSelector={userEmail} onValid={this.onValid} onInvalid={this.onInvalid}/>
183
184 <button disabled={!this.state.hasAgreed} type="submit">Submit</button>
185 </div>
186 }
187}
188```
189
190If 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](https://developer.pactsafe.com/docs/get-to-know-our-javascript-library)
191
192The list below describes the props names and corresponding PactSafe event:
193
194## <a name="onAll"></a> onAll
195_ps event: `all`
196
197A 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.
198
199### Callback Arguments:
200| Name | Type | Description |
201|:----------------:|:------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
202| event | String | The name of the event that was triggered. |
203|[arguments] | Array<Any> | All of the arguments that were passed to the original event. |
204
205## <a name="onSent"></a> onSent
206_ps event: `sent`
207
208Triggered when a `send` command has been completed successfully.
209
210### Callback Arguments:
211| Name | Type | Description |
212|:----------------:|:---------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
213| event_type | String | The type of action that was sent. Supported values include: 'agreed', 'disagreed', 'displayed', 'visited' and 'updated'. |
214| parameters | Object | An object containing the contract and group details that were sent. Contains three parameters: 'contracts', 'versions' and 'group'. |
215| context | Site, BrowsewrapGroup or ClickwrapGroup | The Site or Group object that initiated the send command. |
216| 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. |
217
218## <a name="onRetrieved"></a> onRetrieved
219_ps event: `retrieved`
220
221Triggered when a `retrieved` command has been completed successfully.
222
223### Callback Arguments:
224| Name | Type | Description |
225|:----------------:|:---------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
226| responseJSON | Object | The JSON response body returned by the XMLHttpRequest. |
227| xhr | XMLHttpRequest | The raw XMLHttpRequest that was sent to the Action API. |
228| context | Site, BrowsewrapGroup or ClickwrapGroup | The Site or Group object that initiated the retrieve command. |
229
230## <a name="onSet"></a> onSet
231_ps event: `set`
232
233Triggered 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
234one clickwrap on the page if multiple are mounted in order to guarantee the function is idempotent, otherwise it will be called once per clickwrap.
235
236### Callback Arguments:
237| Name | Type | Description |
238|:----------------:|:--------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
239| parameter | String | The name of the parameter that was set. |
240| value | String, Number, Object, Function, etc. | The raw XMLHttpRequest that was sent to the Action API. |
241| context | Site, BrowsewrapGroup or ClickwrapGroup | The Site or Group object on which the parameter was set. |
242
243## <a name="onSetSignerId"></a> onSetSignerId
244_ps event: `set:signer_id`
245
246Triggered when the signer_id parameter is set.
247
248### Callback Arguments:
249| Name | Type | Description |
250|:----------------:|:--------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
251| value | String | The `signer_id` that was set |
252| context | Site, BrowsewrapGroup or ClickwrapGroup | The Site or Group object on which the parameter was set. |
253
254## <a name="onValid"></a> onValid
255_ps event: `valid`
256
257Triggered when all of the contracts in a Group have been accepted by a signer.
258
259### Callback Arguments:
260| Name | Type | Description |
261|:----------------:|:--------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
262| parameters | Object | An object containing the contracts and versions that belong to the Group. Contains three parameters: 'contracts', 'versions' and 'group' |
263| context | BrowsewrapGroup or ClickwrapGroup | The Group object that was validated |
264
265## <a name="onInvalid"></a> onInvalid
266_ps event: `invalid`
267
268Triggered 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.
269
270### Callback Arguments:
271| Name | Type | Description |
272|:----------------:|:--------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
273| parameters | Object | An object containing the contracts and versions that belong to the Group. Contains three parameters: 'contracts', 'versions' and 'group' |
274| context | BrowsewrapGroup or ClickwrapGroup | The Group object that was invalidated |
275
276## <a name="onRendered"></a> onRendered
277_ps event: `rendered`
278
279Triggered when a Group object has been rendered.
280
281### Callback Arguments:
282| Name | Type | Description |
283|:----------------:|:--------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
284| context | ClickwrapGroup | The Group object that was rendered |
285
286## <a name="onDisplayed"></a> onDisplayed
287_ps event: `displayed`
288
289Triggered when a Group object displays a contract.
290
291### Callback Arguments:
292| Name | Type | Description |
293|:----------------:|:--------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
294| element | HTMLElement | The contract's HTMLElement that was displayed. |
295| context | ClickwrapGroup | The Group object that displayed the contract |
296
297## <a name="onScrolled"></a> onScrolled
298_ps event: `scrolled`
299
300Triggered 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.
301
302### Callback Arguments:
303| Name | Type | Description |
304|:----------------:|:--------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
305| contractsElement | Object | The element containing the entire container selector of the group. |
306| context | ClickwrapGroup | The Group object that had all contracts scrolled to the bottom |
307
308
309## <a name="onScrolledContract"></a> onScrolledContract
310_ps event: `scrolled:contract`
311
312Triggered 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.
313
314### Callback Arguments:
315| Name | Type | Description |
316|:----------------:|:--------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
317| contractHTML | Object | An object containing the HTML of the contract that has been scrolled to the bottom. |
318| group | ClickwrapGroup | The Group object that was scrolled to the bottom |
319
320## <a name="onError"></a> onError
321_ps event: `error`
322
323Triggered when a send or retrieve command encounters an error before being sent.
324
325### Callback Arguments:
326| Name | Type | Description |
327|:-------------------:|:--------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------:|
328| message | String | A message describing why the error occurred. |
329| event_type | String | The type of action that was being sent. |
330| context | Site, BrowsewrapGroup, or ClickwrapGroup | The Site or Group object that initiated the command.
331
332---
333
334### PSBrowseWrap Props:
335
336| Prop | Type | Default | Required? | Description |
337|:----------------------:|:------------------------------------------------------------------:|:---------------------------------------:|:----------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
338| `accessId` | string | Required Value | Yes | PactSafe site access ID |
339| `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. |
340| `badgeText` | string | value of `linkText` | No | Provide alternate text for the BrowseWrap badge |
341| `groupKey` | string | null | Yes | PactSafe group key, this is found within the PactSafe Groups configuration. |
342| `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 |
343| `linkText` | string | null | Yes | The text that your BrowseWrap link will display (for example, 'Legal Center' or 'Terms of Service') |
344| `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. |
345| `position` | string.oneOf[`'middle'`, `'left'`, `'right'`, `'auto'`] | auto | Yes | Position of where the BrowseWrap badge will float within the browser window |
346| `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. |
347
348## Development (`src`, `lib` and the build process)
349
350[See CONTRIBUTING.md](CONTRIBUTING.md)
351
352
353## License
354
355Copyright &copy; 2019 PactSafe.
356
357[npm-badge]: https://img.shields.io/npm/v/@pactsafe/pactsafe-react-sdk.svg
358[npm]: https://www.npmjs.com/package/@pactsafe/pactsafe-react-sdk
\No newline at end of file