Angular SDK

PactSafe Angular SDK

Angular SDK for easy Clickwrap/Browsewrap implementation leveraging PactSafe's JavaScript Library

Features

  • Automatically loads the PactSafe Snippet into your app so all you have to do is call _ps to use the PactSafe Library

PSClickWrap Component:

  • Renders a PactSafe ClickWrap group by providing a site accessId and a groupKey
  • Have more control on what contracts you show by using a filter to specify contract ID's and/or tags
  • Render a completely dynamic Clickwrap by passing in render_data
  • Override default properties set within PactSafe's App configuration:
    • ClickWrap Style using clickWrapStyle (only when using filter as well)
    • Signer ID selector using signerIdSelector
    • and more! (See more detailed documentation on available PSClickWrap configurations below)

PSBrowseWrap Component:

  • Renders a PactSafe BrowseWrap grou by providing a site accessId and groupKey
  • Override default properties set within PactSafe's App configuration:
    • Position with position
    • Visability with alwaysVisible
    • and more! (See more detailed documentation on available PSBrowseWrap configurations below)

Demo & Example

PSClickWrap Component:

PSClickWrap

PSBrowseWrap Component:

PSBrowseWrap

Example

Included in the project is an example folder. To run the example, navigate to the root of the example folder, then:

npm install http-server -g
http-server

Open a browser and go to localhost:8081 and the example app should be running and you can see the components in action.

If the app is having permission issues when trying to run, try running the server as an https server as follows:

// Create self-signed SSL
openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
// Run SSL Server
http-server -S -C cert.pem -o

Installation

The easiest way to use pactsafe-angular-sdk is to install it using NPM and include it in your own Angular 2+ build process.
The module provides you with the transpiled code and an example project using the sdk.

npm install pactsafe-angular-sdk --save

Alternatively, for more flexability, you can clone the repository, allowing you to modify the source code easier, and then use gulp (already preconfigured) to build your src.

  • Clone
  • Modify src how you want
  • gulp build
  • Use dist in your project as you would with the npm module

Usage

Using PSClickWrap

In order to use the PSClickWrap component, you must import PSModule from pactsafe-angular-sdk into your main module

PSClickWrap Component:

// app.module.ts

import { PSModule } from 'pactsafe-angular-sdk'
// ...
@NgModule({
  // ...
  imports: [
    PSModule.forRoot(),
    // Other imports
  ],
  // ...
})

With the PSModule properly imported, you should be able to use the PSClickWrap component throughout your project.
The ClickWrap requires you to specify an accessId, one of ( groupKey or filter ), and one of (signerIdSelector, signerId). The signerIdSelector corresponds to an input element whose input will identify the signer (usually an email field), so when the user accepts your terms, the info can be successfully sent to PactSafe. The signerId just takes a string and assigns that string as the user's id instead of using the input field, allowing you to programmatically assign this information if need be.

<!-- sample.component.html -->

<input type="email" id="userEmail" placeholder="Your Email"/>

<ps-click-wrap accessId={YOUR_PACTSAFE_ACCESS_ID_HERE} groupKey={YOUR_GROUP_KEY_HERE} signerIdSelector="userEmail"></ps-click-wrap>

<!-- Using signerId instead -->

<ps-click-wrap accessId={YOUR_PACTSAFE_ACCESS_ID_HERE} groupKey={YOUR_GROUP_KEY_HERE} signerId="JaneDoe"></ps-click-wrap>

Replace 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 PacSafe group's configuration

Pass in any additional options using inputs on the ps-click-wrap component as shown above with accessId, groupKey, and signerIdSelector

Using PSBrowseWrap

In order to use the PSBrowseWrap component, you must import PSModule from pactsafe-angular-sdk into your main module exactly as shown above for the PSClickWrap

With the PSModule properly imported, you should be able to use the PSBrowseWrap component throughout your project.
The BrowseWrap requires you to specify an accessId, groupKey, and a linkText.

<!-- sample.component.html -->

<ps-browse-wrap accessId={YOUR_PACTSAFE_ACCESS_ID_HERE} groupKey={YOUR_GROUP_KEY_HERE} linkText={YOUR_LINK_TEXT_HERE}></ps-browse-wrap>

Replace 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 PacSafe group's configuration

Replace YOUR_LINK_TEXT_HERE with the text you want displyed for your link generated by the BrowseWrap

Pass in any additional options using inputs on the ps-browse-wrap component as shown above with accessId, groupKey, and linkText

Inputs/Configurations for ClickWrap and BrowseWrap Components

PSClickWrap Inputs:
InputTypeDefaultRequired?Description
accessIdstringnullYesPactSafe site access ID
clickWrapStylestring.oneOf['full', 'scroll', 'checkbox', 'combined', 'embedded']Value specified in PactSafe Group's UINoOverride the clickwrap style specified in the PactSafe Group Interface (only works if using filter instead of groupKey)
confirmationEmailboolValue specified in PactSafe Group's UINoOverride whether to send a confirmation email to the signer upon contract acceptance
containerNamestringps-clickwrapNo, but encouraged if using more than one contract in a groupThe div ID that will contain your clickwrap. You should override this if you plan on displaying more than one contract on a page.
disableSendingboolfalseNoTurn 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.
displayAllbooltrueNoDisplay all contracts in the group immediately. If disabled, a contract will only be displayed if the signer hasn't accepted the latest version.
displayImmediatelybooltrueNoDisplay the group's contracts as soon as the Signer ID is available. If disabled, contracts will remain hidden until you call displayRequired()
dynamicboolfalseNoIf 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.
filterstringnullIf groupKey prop is not passedAllows 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.
forceScrollboolValue specified in PactSafe Group's UINoDisable acceptance until the signer scrolls to the bottom of each contract.
groupKeystringnullIf filter prop is not passedPactSafe group key, this is found within the PactSafe Groups configuration.
renderDataobjectnullIf dynamic is set to trueObject containing the dynamic render data for your contract. For more information on using dynamic contracts, check out this documentation.
signerIdstringnullIf signerIdSelector prop is not passedThe ID that will be used to identify the signer (this option lets you programmatically assign the Id instead of using an input field with signerIdSelector.
signerIdSelectorstringnullIf signerId prop is not passedThe ID of the <input> element that will be used to identify the signer.
testModeboolfalseNoEnable this to register any contract acceptances as test data that can be cleared within the PactSafe UI
PSBrowseWrap Inputs:
InputTypeDefaultRequired?Description
accessIdstringnullYesPactSafe site access ID
alwaysVisibleboolfalseNoKeep the badge visible on the page at all times. If disabled, the badge will be hidden if the target link is visible on screen.
badgeTextstringvalue of linkTextNoProvide alternate text for the BrowseWrap badge
groupKeystringnullYesPactSafe group key, this is found within the PactSafe Groups configuration.
linkstringnullIf openLegalCenter is set to falseLocation 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
linkTextstringnullYesThe text that your BrowseWrap link will display (for example, 'Legal Center' or 'Terms of Service')
openLegalCenterbooltrueNoOpen this group's legal center page when the badge or link is clicked. If enabled, the target link's original href will be replaced.
positionstring.oneOf['middle', 'left', 'right', 'auto']autoNoPosition of where the BrowseWrap badge will float within the browser window

Notes

  • You must run your web app over HTTPS in order to interact with the PactSafe Activity API (that powers both the PSClickWrap and PSBrowseWrap components)!

  • If you are developing in an AngularCli generated project, you may run into trouble using the library. Make sure you set up a path mapping in /src/tsconfig.app.json of your consuming application (not the library) and that should solve any compilation problems you may have:

{
  "compilerOptions": {
    // ...
    // Note: these paths are relative to 'baseUrl' path.
    "paths": {
      "@angular/*": [
        "../node_modules/@angular/*"
      ]
    }
  }
}
  • Both the components load in the ps library giving you access to the _ps global. With that, you can add more advance functionality (checking whether all contracts have been accepted, sending data only on form submit, etc.)
    • _ps is defined as a global in the window, so you can access it from any of your angular components
    • If you are having trouble with the linter using _ps, include declare var _ps: any; at the top of the file you are trying to use it in. This just tells the linter that _ps exists.

License

Copyright (c) 2017 PactSafe.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.