|
|
Getting Started Guide: Access and Licensing
The Enterprise Web Services (EWS) includes authentication and authorization that
govern access to the system, enforce quota restrictions, and determined which operations can be performed.
Enrollment, Payment Plans, and Payment Methods
Yahoo! Search Marketing supports various enrollment options, payment plans, and payment methods. To place these features within the context of EWS and the Search Marketing APIs, a brief overview is given here.
Note: If you have any questions about the enrollment process, your accounts, payment plans, or payment methods, please contact your Technical Account Management team.
Enrollment
Customers can enroll with Yahoo! Search Marketing using these options:
- Online signup through the web application - Self Service or Assisted Setup.
- Online signup through a reseller using EWS and the MasterAccountService and the addNewCustomer operation.
During the enrollment process the following are created:
- a master account,
- an initial account under that master account, and
- a user who assumes the role of master account administrator.
During the enrollment process you also determine your payment plan and payment method and whether to use a credit card.
- The payment plan is associated with the company and applies to all accounts under the master account.
- The payment method is associated with the account, which means that individual accounts under a master account can have different payment methods.
- The credit card belongs to the user and may be associated with more than one account.
After the enrollment process is completed, and you decide to add more accounts under the master account, these new accounts will inherit the payment plan already in effect for that company and the payment method of the oldest account under that master account. You can subsequently change the payment method using the AccountService and the setActiveCreditCard operation.
Payment Plans and Payment Methods
Yahoo! Search Marketing supports these payment plans - prepay nonstop, prepay deposit, and invoice.
Yahoo! Search Marketing supports these payment methods - credit card, check, bank transfers, and wire transfers.
The prepay nonstop payment plan requires you to add a credit card to the system. The prepay deposit and invoice payment plans work with credit cards, checks, bank transfers, or wire transfers.
Market Support for Online Signup
Not all markets support the prepay deposit payment plan and not all markets support credit cards during online signup.
For the following sections, refer to the VaultService, addNewCustomer operation and the CreditCardInfo data object.
Prepay Nonstop or Prepay Deposit
For the AU, BR, HK, IN, JP, MX, NL, NO, SG, and TW markets, you can provide a credit card number or pass in the null string via EWS. If you provide a credit card number, a prepay nonstop account is created. If you pass in the null string, a prepay deposit account is created and the user can add a credit card later via the web application.
For the BR market and prepay deposit accounts only, in addition to credit cards, you can also use Boleto Bancario, a bank transfer payment method that is configured via the web application.
Prepay Nonstop Only
For the AT, CA, CH, DE, DK, ES, FI, FR, IT, SE, UK, and US markets, you can provide the credit card number or pass in the null string via EWS. If you provide a credit card number, a prepay nonstop account is created. If you pass in the null string, a prospect is created and the user can complete the enrollment process later using the web application.
Prepay Deposit Only
For the KR market, a prepay deposit account is automatically created when you pass in the null string via EWS. The user can make payments later using the web application using a special plug-in.
Note: The KR market does not support storing credit card information with your account information. If you provide the credit card information using the addNewCustomer operation or the addCreditCard or setActiveCreditCard operations, it will have no effect.
Licensing, Authentication, and Login
When you enroll with Yahoo! Search Marketing, you obtain an EWS license that includes your license key, command groups, and quota.
Your Technical Account Management team will help you set up the initial username and password, and create an initial master account and an account, which you can use as a starting point to add more users and accounts, or to begin building your campaigns. See the MasterAccountService Overview.
Your license key, username, and password are basic forms of authentication and must be included in every EWS request. You may also use the same username and password to log onto the web application.
You can change your own password through the web application or using the UserManagementService. Or, you can have an administrator or manager request a password change for you using the UserManagementService. See the UserManagementService Overview.
Command Groups and Quotas
In addition to the license key, your EWS license specifies the command groups you have access to and the quota you have been granted.
A command group is a set of one or more operations. A quota is the total number of requests you can make in a 24-hour period using any of the operations in a command group. Your command groups and quota may vary depending on whether you are using the sandbox or the production system.
Command Groups
The command groups are described in the table. The Marketing API Reference lists the command group each operation belongs to.
| Command Group | Description |
|---|---|
| AccountManagement |
A set of operations for managing your accounts. |
| AdvancedTools |
A set of operations intended for high-volume tools. |
| BasicReports |
A set of operations for requesting and retrieving performance metrics for your campaigns. |
| Beta | A set of operations that expose an early version of APIs for users to adopt. |
| BidInformation | An operation for providing real-time information on current marketplace bids for a keyword. |
| Bulk | A set of operations to download an account's objects using files based on YSM bulk templates |
| CampaignOptimization | A set of operations for managing campaign, ad group, and keyword optimization guidelines. |
| CustomerManagement |
An operation for enrolling new customers with Yahoo! Search Marketing. |
| Marketing |
A set of operations for managing your campaigns. |
| Research |
A set of operations for discovering new keywords and estimating keyword performance. |
| Vault |
A set of operations for managing sensitive user and account information. |
Quotas
Each EWS request includes either an operation, for example, getKeyword, or a list-based operation, for example, getKeywords that counts against your quota.See Tracking Quota for EWS Requests. For each operation, one quota point is deducted. For each list-based operation, one quota point is deducted for each object in the list.
Each EWS response includes elements in the SOAP header that show the command group to which the operation belongs and the remaining quota for that command group. You can use this information to track your quota consumption and to manage your EWS requests.See Tracking Quota for EWS Responses.
When you exceed your quota for any command group, additional EWS requests are rejected with a Quota Exceeded SOAP fault. Your quota is reset at midnight in time zone of the master account.
Roles and Capabilities
Your EWS license specifies your command groups and quota. What operations you can actually perform are based on the roles and capabilities that are assigned to you.
A role is a set of one or more capabilities. A capability is a set of tasks a user can perform, based on the assigned role. In short, a role is a simple way to assign one or more capabilities to a user.
Roles
A role is assigned to a user for a specific master account or account. When
you enroll for Yahoo! Search Marketing, the initial username is granted the role of MasterAccountAdministrator for the initial master account and account.
As shown in the table, EWS defines five possible roles, each with decreasing levels of capabilities.
| Role | Description |
|---|---|
| MasterAccountAdministrator |
The MasterAccountAdministrator has full access to the master account; has AccountManager access to all accounts under that master account; and can grant MasterAccountAdministrator, AccountManager, CampaignManager, or Analyst roles to other users for all accounts under that master account. |
| AccountManager |
The AccountManager has full access to specific accounts under a master account but not to the master account itself; has CampaignManager access to the campaigns under those accounts; and can grant AccountManager, CampaignManager, or Analyst roles to other users for those accounts. |
| CampaignManager |
The CampaignManager has full access to specific campaigns as well as the ad groups, keywords, excluded keywords, and ads under those campaigns, and can run reports and perform research tasks. |
| Analyst |
An Analyst can read campaign data, run reports, and perform research tasks, but cannot change any data. |
| MasterAccountUser | This is an internal role granted on Master Account for users who have the AccountManager, CampaignManager, and Analyst rights, to indicate that they may select the Master Account for login. |
Capabilities
Capabilities are related to product areas and map to specific operations. For example, the CampaignWrite capability includes those operations that allow you to add, update, and delete campaigns, ad groups, ads, and keywords. The CampaignRead capability include those operations that allow you to get information about campaigns, ad groups, ads, and keywords.
The capabilities for each role are shown in the table below. The Marketing API Reference lists the required capability for each operation.
| Capability | MasterAccount Administrator |
Account Manager |
Campaign Manager |
Analyst |
Master Account User |
|---|---|---|---|---|---|
| AccountRead |
X |
X |
X |
X |
X |
| AccountWrite |
X |
X |
X |
||
| AccountUserManagementRead |
X |
X |
X |
||
| AccountUserManagementWrite |
X |
X |
X |
||
| BatchRead | X |
X |
X |
X |
|
| CampaignRead |
X |
X |
X |
X |
X |
| CampaignWrite |
X |
X |
X |
X |
|
| MasterAccountRead |
X |
||||
| MasterAccountWrite |
X |
||||
| MasterAccountUserManagementWrite |
X |
||||
| PlatformServices |
X |
X |
X |
X |
X |
| Reporting |
X |
X |
X |
X |
X |
| Research |
X |
X |
X |
X |
X |
| SelfCare |
X |
X |
X |
X |
X |
Command Groups and Quotas vs. Roles and Capabilities
Command groups and quotas are different from roles and capabilities. Command groups and quotas determine which operations you can perform, and how often you can perform them. Roles and capabilities determine which users in your company can perform specific operations and tasks.
For example, a company's license may grant a quota of 10,000 calls for the operations of a particular command group; however, if the username included in the EWS request does not have the right role and capability for the specified operation, the request will fail.
Conversely, the username in the EWS request may have the correct role and capability for the operation in question; however, if the company’s license does not grant any quota for the command group the operation belongs to, the request will fail. This is mapped in the grid shown below:
| Y!SM License | Operations |
Users |
|---|---|---|
Command Groups |
Command Group |
Roles |
Quotas |
Capability |
Capabilities |
On-Behalf-Of Authorizations
A common usage of the Search Marketing APIs is for third-parties, for example, agencies, resellers, and search engine marketers to perform work on behalf of other users, for example, advertisers. For this to happen:
- The third-party must obtain their own license, username, and password from Yahoo! Search Marketing.
- The advertiser should create an "on-behalf-of" user for the third party and give the "on-behalf-of" user only those authorizations that are necessary to perform the required work.
For example, if an advertiser hires an agency to manage the campaigns for a specific account, the advertiser needs to create an "on-behalf-of" user using the UserManagementService and the addUser operation, and then assign the "on-behalf-of" user the role of CampaignManager for the account using the UserManagementService and the addAuthorizationForUser operation.
Once the "on-behalf-of" user is set up, the agency can perform work on behalf of the advertiser; that is, send requests to EWS using the operations from the Marketing API. To do so, the agency must include their own credentials - username, password, license, as well as the credentials of the advertiser - masterAccountID, accountID, onBehalfOfUsername, and onBehalfOfPassword in the SOAP header of the request. See EWS Requests.
Advertisers who work with third parties are strongly encouraged to set up a separate "on-behalf-of" user for each third party which needs access to their accounts or campaigns and to provide only those authorizations that are absolutely necessary. Doing so will help ensure that the advertiser's accounts and campaigns are protected.